From 94e8b8c3164eb6ca920aab1277b6a39573304b7e Mon Sep 17 00:00:00 2001 From: zcp100_zcp100 Date: Sun, 9 Oct 2022 15:57:40 +0800 Subject: [PATCH 1/3] =?UTF-8?q?add(mogdb0):=E6=9B=B4=E6=96=B0v3.1=E7=9A=84?= =?UTF-8?q?=E4=B8=AD=E6=96=87toc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../AI-features/1-AI-features-overview.md | 18 + .../intelligence-explain-best-practices.md | 32 + ...lligence-explain-environment-deployment.md | 205 ++ .../intelligence-explain-faqs.md | 35 + .../intelligence-explain-overview.md | 14 + .../intelligence-explain-user-guide.md | 207 ++ .../1-1-x-tuner-overview.md | 10 + .../1-2-preparations.md | 198 ++ .../1-3-examples.md | 162 ++ .../1-4-obtaining-help-information.md | 58 + .../1-5-command-reference.md | 50 + .../1-6-Troubleshooting.md | 13 + .../2-1-single-query-index-recommendation.md | 71 + .../2-2-virtual-index.md | 125 ++ ...2-3-workload-level-index-recommendation.md | 117 + .../3-1-overview.md | 10 + .../3-2-environment-deployment.md | 11 + .../3-3-usage-guide.md | 34 + .../3-4-obtaining-help-information.md | 41 + .../3-5-command-reference.md | 20 + .../3-6-troubleshooting.md | 12 + .../4-1-overview.md | 10 + .../4-2-environment-deployment.md | 10 + .../4-3-usage-guide.md | 34 + .../4-4-obtaining-help-information.md | 38 + .../4-5-command-reference.md | 21 + .../4-6-troubleshooting.md | 11 + .../5-1-overview.md | 18 + .../5-2-usage-guide.md | 96 + .../5-3-obtaining-help-information.md | 49 + .../5-4-command-reference.md | 17 + .../5-5-troubleshooting.md | 11 + .../ai4db/ai4db-autonomous-database-o&m.md | 34 + .../components-that-support-dbmind.md | 10 + .../prometheus-exporter-command-reference.md | 136 ++ ...metheus-exporter-environment-deployment.md | 33 + ...eus-exporter-obtaining-help-information.md | 15 + .../prometheus-exporter-overview.md | 12 + .../prometheus-exporter-troubleshooting.md | 16 + .../prometheus-exporter-usage-guide.md | 62 + .../ai4db/dbmind-mode/1-service.md | 148 ++ .../ai4db/dbmind-mode/2-component.md | 37 + .../AI-features/ai4db/dbmind-mode/3-set.md | 54 + .../ai4db/dbmind-mode/dbmind-mode.md | 47 + .../v3.1/AI-features/db4ai/db4ai.md | 10 + ...i-snapshots-for-data-version-management.md | 266 +++ .../db4ai/full-process-ai/full-process-ai.md | 12 + .../full-process-ai/plpython-fenced-mode.md | 135 ++ .../AI-features/db4ai/native-db4ai-engine.md | 317 +++ product/zh/docs-mogdb/v3.1/_index.md | 90 + .../MogDB-compared-to-openGauss.md | 134 ++ .../about-mogdb/mogdb-new-feature/3.0.0.md | 193 ++ .../about-mogdb/mogdb-new-feature/3.0.1.md | 84 + .../about-mogdb/mogdb-new-feature/3.0.2.md | 156 ++ .../mogdb-new-feature/release-note.md | 14 + .../1-enhanced-opengauss-kernel.md | 12 + .../2-docker-based-mogdb.md | 37 + ...-wal2json-extention-for-mogdb&opengauss.md | 125 ++ .../open-source-components/DBMS-RANDOM.md | 532 +++++ .../open-source-components/compat-tools.md | 18 + .../open-source-components/mog_filedump.md | 106 + .../open-source-components/mog_xlogdump.md | 305 +++ .../open-source-components/mogdb-monitor.md | 27 + .../v3.1/about-mogdb/terms-of-use.md | 22 + .../v3.1/about-mogdb/usage-limitations.md | 27 + .../v3.1/administrator-guide/br/1-1-br.md | 95 + .../v3.1/administrator-guide/br/1-2-br.md | 139 ++ .../v3.1/administrator-guide/br/1-3-br.md | 24 + .../v3.1/administrator-guide/br/1-4-br.md | 204 ++ .../column-store-tables-management.md | 401 ++++ ...-and-gs_dumpall-to-export-data-overview.md | 91 + .../2-exporting-a-single-database.md | 305 +++ .../3-exporting-all-databases.md | 133 ++ ...-by-a-user-without-required-permissions.md | 86 + .../importing-data/1-import-modes.md | 18 + ...10-managing-concurrent-write-operations.md | 195 ++ ...ing-the-INSERT-statement-to-insert-data.md | 20 + ...OPY-FROM-STDIN-statement-to-import-data.md | 318 +++ ...sing-a-gsql-meta-command-to-import-data.md | 211 ++ .../5-using-gs_restore-to-import-data.md | 272 +++ .../6-updating-data-in-a-table.md | 176 ++ .../importing-data/7-deep-copy.md | 122 ++ .../importing-data/8-ANALYZE-table.md | 50 + .../9-doing-VACUUM-to-a-table.md | 22 + .../localization/character-set-support.md | 206 ++ .../localization/collation-support.md | 128 ++ .../localization/locale-support.md | 68 + .../1-introducing-mot/1-mot-introduction.md | 29 + .../2-mot-features-and-benefits.md | 22 + .../3-mot-key-technologies.md | 24 + .../4-mot-usage-scenarios.md | 22 + .../5-mot-performance-benchmarks.md | 204 ++ .../2-using-mot/1-using-mot-overview.md | 18 + .../2-using-mot/2-mot-preparation.md | 226 ++ .../2-using-mot/3-mot-deployment.md | 706 ++++++ .../mot-engine/2-using-mot/4-mot-usage.md | 544 +++++ .../2-using-mot/5-mot-administration.md | 456 ++++ .../6-mot-sample-tpcc-benchmark.md | 116 + .../mot-engine/3-concepts-of-mot/3-1.md | 95 + .../mot-engine/3-concepts-of-mot/3-2.md | 191 ++ .../mot-engine/3-concepts-of-mot/3-3.md | 71 + .../mot-engine/3-concepts-of-mot/3-4.md | 22 + .../mot-engine/3-concepts-of-mot/3-5.md | 43 + .../mot-engine/3-concepts-of-mot/3-6.md | 208 ++ .../mot-engine/3-concepts-of-mot/3-7.md | 24 + .../mot-engine/3-concepts-of-mot/3-8.md | 79 + .../mot-engine/3-concepts-of-mot/3-9.md | 33 + .../mot-engine/4-appendix/1-references.md | 40 + .../mot-engine/4-appendix/2-glossary.md | 59 + .../primary-and-standby-management.md | 134 ++ .../0-starting-and-stopping-mogdb.md | 219 ++ .../1-routine-maintenance-check-items.md | 178 ++ ...0-data-security-maintenance-suggestions.md | 29 + .../routine-maintenance/11-log-reference.md | 153 ++ .../2-checking-os-parameters.md | 180 ++ .../3-checking-mogdb-health-status.md | 648 ++++++ .../4-checking-database-performance.md | 85 + .../5-checking-and-deleting-logs.md | 164 ++ .../6-checking-time-consistency.md | 52 + ...g-the-number-of-application-connections.md | 133 ++ .../8-routinely-maintaining-tables.md | 111 + .../9-routinely-recreating-an-index.md | 72 + .../routine-maintenance/slow-sql-diagnosis.md | 29 + .../using-the-gsql-client-for-connection.md | 212 ++ .../v3.1/administrator-guide/upgrade-guide.md | 360 ++++ .../predictor-ai-query-time-forecasting.md | 48 + ...ection-forecast-and-exception-detection.md | 41 + ...-cause-analysis-for-slow-sql-statements.md | 38 + .../3-index-recommendation.md | 40 + .../4-parameter-tuning-and-diagnosis.md | 46 + .../5-slow-sql-statement-discovery.md | 39 + .../db4ai-database-driven-ai.md | 39 + .../1-standard-sql.md | 38 + .../2-standard-development-interfaces.md | 36 + .../3-postgresql-api-compatibility.md | 36 + .../4-pl-java.md | 66 + .../MogDB-MySQL-compatibility.md | 30 + .../MogDB-Oracle-compatibility.md | 30 + .../characteristic-description-overview.md | 112 + .../1-access-control-model.md | 41 + .../10-row-level-access-control.md | 43 + .../11-password-strength-verification.md | 71 + ...ity-query-in-a-fully-encrypted-database.md | 110 + .../13-ledger-database-mechanism.md | 43 + .../14-transparent-data-encryption.md | 53 + ...ation-of-control-and-access-permissions.md | 46 + .../3-database-encryption-authentication.md | 36 + .../4-data-encryption-and-storage.md | 44 + .../database-security/5-database-audit.md | 36 + .../6-network-communication-security.md | 44 + .../database-security/7-resource-label.md | 49 + .../database-security/8-unified-audit.md | 68 + .../9-dynamic-data-anonymization.md | 93 + ...ort-for-functions-and-stored-procedures.md | 38 + .../10-autonomous-transaction.md | 44 + .../11-global-temporary-table.md | 45 + .../12-pseudocolumn-rownum.md | 43 + .../13-stored-procedure-debugging.md | 38 + ...-load-balancing-and-readwrite-isolation.md | 36 + .../15-in-place-update-storage-engine.md | 36 + .../16-publication-subscription.md | 52 + .../17-foreign-key-lock-enhancement.md | 45 + .../18-data-compression-in-oltp-scenarios.md | 29 + .../19-transaction-async-submit.md | 30 + .../enterprise-level-features/2-sql-hints.md | 40 + .../20-copy-import-optimization.md | 95 + .../21-dynamic-partition-pruning.md | 32 + .../22-sql-running-status-observation.md | 107 + .../23-index-creation-parallel-control.md | 28 + .../24-brin-index.md | 257 +++ .../25-bloom-index.md | 211 ++ .../26-backend-compression.md | 28 + .../3-full-text-indexing.md | 53 + .../4-copy-interface-for-error-tolerance.md | 36 + .../5-partitioning.md | 58 + ...support-for-advanced-analysis-functions.md | 57 + .../7-materialized-view.md | 36 + .../8-hyperloglog.md | 38 + .../9-creating-an-index-online.md | 40 + .../high-availability/1-primary-standby.md | 42 + .../10-adding-or-deleting-a-standby-server.md | 59 + ...-entering-the-maximum-availability-mode.md | 42 + .../12-parallel-logical-decoding.md | 53 + .../high-availability/13-dcf.md | 45 + .../high-availability/14-cm.md | 62 + .../high-availability/15-global-syscache.md | 43 + ...-a-standby-node-to-build-a-standby-node.md | 36 + .../2-logical-replication.md | 37 + .../3-online-node-replacement.md | 36 + .../high-availability/4-logical-backup.md | 40 + .../high-availability/5-physical-backup.md | 52 + .../6-automatic-job-retry-upon-failure.md | 93 + .../high-availability/7-ultimate-rto.md | 39 + .../8-cascaded-standby-server.md | 45 + .../high-availability/9-delayed-replay.md | 46 + .../high-performance/1-cbo-optimizer.md | 36 + .../high-performance/10-xlog-no-lock-flush.md | 36 + .../11-parallel-page-based-redo-for-ustore.md | 36 + ...store-execution-to-vectorized-execution.md | 40 + .../high-performance/2-llvm.md | 36 + .../high-performance/3-vectorized-engine.md | 43 + .../4-hybrid-row-column-store.md | 72 + .../5-adaptive-compression.md | 42 + .../high-performance/6-sql-by-pass.md | 36 + ...-kunpeng-numa-architecture-optimization.md | 40 + .../8-high-concurrency-of-thread-pools.md | 37 + .../9-smp-for-parallel-execution.md | 44 + .../maintainability/1-gray-upgrade.md | 36 + .../2-workload-diagnosis-report.md | 72 + .../maintainability/3-slow-sql-diagnosis.md | 137 ++ .../4-session-performance-diagnosis.md | 106 + .../5-system-kpi-aided-diagnosis.md | 66 + .../maintainability/fault-diagnosis.md | 34 + ...a-distributed-database-using-kubernetes.md | 36 + .../distributed-database-capability.md | 36 + .../mogdb-client-tool-datastudio.md | 57 + ...mysql-to-mogdb-migration-tool-chameleon.md | 37 + ...core-dump-occurs-due-to-full-disk-space.md | 22 + ...settings-of-guc-parameter-log-directory.md | 20 + ...e-dump-occurs-when-removeipc-is-enabled.md | 24 + ...e-dump-occurs-after-installation-on-x86.md | 26 + ...-disk-space-usage-reaches-the-threshold.md | 58 + .../11-slow-response-to-a-query-statement.md | 48 + ...alyzing-the-status-of-a-query-statement.md | 57 + .../13-forcibly-terminating-a-session.md | 62 + ...ng-whether-a-query-statement-is-blocked.md | 56 + .../15-low-query-efficiency.md | 32 + .../16-lock-wait-timeout-is-displayed.md | 25 + .../17-table-size-does-not-change.md | 39 + ...ed-when-the-table-partition-is-modified.md | 46 + .../19-different-data-is-displayed.md | 32 + .../2-when-the-tpcc-is-running.md | 20 + ...hen-a-user-specifies-only-an-index-name.md | 47 + .../21-reindexing-fails.md | 29 + ...-error-occurs-during-integer-conversion.md | 24 + .../23-too-many-clients-already.md | 50 + .../24-b-tree-index-faults.md | 68 + ...3-standby-node-in-the-need-repair-state.md | 20 + .../4-insufficient-memory.md | 20 + .../5-service-startup-failure.md | 91 + ...or-no-space-left-on-device-is-displayed.md | 64 + .../7-after-you-run-the-du-command.md | 32 + ...-file-is-damaged-in-the-xfs-file-system.md | 22 + .../9-primary-node-is-hung-in-demoting.md | 24 + .../common-fault-locating-methods.md | 283 +++ .../developer-guide/1-1-stored-procedure.md | 16 + ...-introduction-to-autonomous-transaction.md | 12 + ...ction-supporting-autonomous-transaction.md | 56 + ...edure-supporting-autonomous-transaction.md | 45 + .../autonomous-transaction/4-restrictions.md | 150 ++ ...block-supporting-autonomous-transaction.md | 36 + .../dev/1-development-specifications.md | 753 +++++++ .../1-development-based-on-jdbc-overview.md | 10 + .../10-example-common-operations.md | 286 +++ ...e-retrying-sql-queries-for-applications.md | 205 ++ ...-and-exporting-data-through-local-files.md | 119 ++ ...rating-data-from-a-my-database-to-mogdb.md | 98 + .../14-example-logic-replication-code.md | 166 ++ ...-to-the-database-in-different-scenarios.md | 78 + .../15-JDBC/1-java-sql-Connection.md | 67 + .../15-JDBC/10-javax-sql-DataSource.md | 21 + .../15-JDBC/11-javax-sql-PooledConnection.md | 19 + .../15-JDBC/12-javax-naming-Context.md | 25 + ...-javax-naming-spi-InitialContextFactory.md | 16 + .../15-JDBC/14-CopyManager.md | 47 + .../15-JDBC/2-java-sql-CallableStatement.md | 46 + .../15-JDBC/3-java-sql-DatabaseMetaData.md | 217 ++ .../15-JDBC/4-java-sql-Driver.md | 22 + .../15-JDBC/5-java-sql-PreparedStatement.md | 70 + .../15-JDBC/6-java-sql-ResultSet.md | 154 ++ .../15-JDBC/7-java-sql-ResultSetMetaData.md | 43 + .../15-JDBC/8-java-sql-Statement.md | 69 + .../9-javax-sql-ConnectionPoolDataSource.md | 17 + ...kage-driver-class-and-environment-class.md | 57 + .../3-development-process.md | 12 + .../4-loading-the-driver.md | 19 + .../5-connecting-to-a-database.md | 111 + .../6-connecting-to-a-database-using-ssl.md | 152 ++ .../7-running-sql-statements.md | 256 +++ .../8-processing-data-in-a-result-set.md | 84 + .../8.1-log-management.md | 231 ++ .../9-closing-a-connection.md | 17 + .../1-development-based-on-odbc-overview.md | 34 + ...es-dependent-libraries-and-header-files.md | 14 + ...nfiguring-a-data-source-in-the-linux-os.md | 334 +++ .../4-development-process.md | 44 + ...mple-common-functions-and-batch-binding.md | 440 ++++ ...pplication-scenarios-and-configurations.md | 496 +++++ .../6-ODBC/2-0-odbc-overview.md | 10 + .../6-ODBC/2-1-SQLAllocEnv.md | 10 + .../6-ODBC/2-10-SQLExecDirect.md | 48 + .../6-ODBC/2-11-SQLExecute.md | 44 + .../6-ODBC/2-12-SQLFetch.md | 43 + .../6-ODBC/2-13-SQLFreeStmt.md | 10 + .../6-ODBC/2-14-SQLFreeConnect.md | 10 + .../6-ODBC/2-15-SQLFreeHandle.md | 43 + .../6-ODBC/2-16-SQLFreeEnv.md | 10 + .../6-ODBC/2-17-SQLPrepare.md | 46 + .../6-ODBC/2-18-SQLGetData.md | 53 + .../6-ODBC/2-19-SQLGetDiagRec.md | 74 + .../6-ODBC/2-2-SQLAllocConnect.md | 10 + .../6-ODBC/2-20-SQLSetConnectAttr.md | 47 + .../6-ODBC/2-21-SQLSetEnvAttr.md | 47 + .../6-ODBC/2-22-SQLSetStmtAttr.md | 47 + .../6-ODBC/2-23-Examples.md | 347 +++ .../6-ODBC/2-3-SQLAllocHandle.md | 45 + .../6-ODBC/2-4-SQLAllocStmt.md | 10 + .../6-ODBC/2-5-SQLBindCol.md | 51 + .../6-ODBC/2-6-SQLBindParameter.md | 59 + .../6-ODBC/2-7-SQLColAttribute.md | 53 + .../6-ODBC/2-8-SQLConnect.md | 54 + .../6-ODBC/2-9-SQLDisconnect.md | 41 + ...e-connection-control-functions-overview.md | 10 + .../10-PQstatus.md | 64 + .../2-PQconnectdbParams.md | 42 + .../3-PQconnectdb.md | 39 + .../4-PQconninfoParse.md | 31 + .../5-PQconnectStart.md | 30 + .../6-PQerrorMessage.md | 34 + .../7-PQsetdbLogin.md | 51 + .../8-PQfinish.md | 34 + .../9-PQreset.md | 34 + .../1-PQclear.md | 34 + .../10-PQntuples.md | 34 + .../11-PQprepare.md | 50 + .../12-PQresultStatus.md | 72 + .../2-PQexec.md | 42 + .../3-PQexecParams.md | 44 + .../4-PQexecParamsBatch.md | 46 + .../5-PQexecPrepared.md | 42 + .../6-PQexecPreparedBatch.md | 44 + .../7-PQfname.md | 36 + .../8-PQgetvalue.md | 42 + .../9-PQnfields.md | 34 + ...synchronous-command-processing-overview.md | 17 + .../2-PQsendQuery.md | 39 + .../3-PQsendQueryParams.md | 52 + .../4-PQsendPrepare.md | 46 + .../5-PQsendQueryPrepared.md | 50 + .../6-PQflush.md | 38 + .../1-PQgetCancel.md | 38 + .../2-PQfreeCancel.md | 34 + .../3-PQcancel.md | 41 + .../dependent-header-files-of-libpq.md | 10 + .../development-process.md | 34 + .../libpq-example.md | 280 +++ .../link-parameters.md | 52 + .../1-psycopg-based-development.md | 19 + .../10.1-example-common-operations.md | 61 + .../1-psycopg2-connect.md | 42 + .../10-connection-close.md | 32 + .../2-connection-cursor.md | 37 + .../3-cursor-execute-query-vars-list.md | 35 + .../4-curosr-executemany-query-vars-list.md | 35 + .../5-connection-commit.md | 32 + .../6-connection-rollback.md | 32 + .../7-cursor-fetchone.md | 30 + .../8-cursor-fetchall.md | 30 + .../9-cursor-close.md | 30 + .../2-psycopg-package.md | 17 + .../3.1-development-process.md | 12 + .../4-loading-a-driver.md | 21 + .../5.1-connecting-to-a-database.md | 11 + .../6-executing-sql-statements.md | 11 + .../7-processing-the-result-set.md | 11 + .../8-closing-the-connection.md | 12 + .../9-connecting-to-the-database-using-ssl.md | 37 + .../developer-guide/dev/5-commissioning.md | 40 + .../foreign-data-wrapper/1-oracle_fdw.md | 51 + .../foreign-data-wrapper/2-mysql_fdw.md | 51 + .../foreign-data-wrapper/3-postgres_fdw.md | 37 + .../foreign-data-wrapper/dblink.md | 79 + .../foreign-data-wrapper/fdw-introduction.md | 10 + .../foreign-data-wrapper/file_fdw.md | 79 + .../logical-decoding/1-logical-decoding.md | 56 + ...cal-decoding-by-sql-function-interfaces.md | 85 + .../publication-subscription/architecture.md | 16 + .../configuration-settings.md | 14 + .../publication-subscription/conflicts.md | 14 + .../publication-subscription/monitoring.md | 14 + .../publication-subscription.md | 20 + .../publication-subscription/publications.md | 22 + .../publication-subscription/quick-setup.md | 36 + .../publication-subscription/restrictions.md | 22 + .../publication-subscription/security.md | 20 + .../publication-subscription/subscriptions.md | 28 + .../1-materialized-view-overview.md | 12 + .../1-full-materialized-view-overview.md | 10 + .../2-full-materialized-view-usage.md | 71 + ...terialized-view-support-and-constraints.md | 22 + ...-incremental-materialized-view-overview.md | 10 + .../2-incremental-materialized-view-usage.md | 92 + ...terialized-view-support-and-constraints.md | 30 + .../benefits-of-partition-pruning.md | 66 + .../dynamic-partition-pruning.md | 260 +++ ...whether-partition-pruning-has-been-used.md | 12 + ...-that-can-be-used-for-partition-pruning.md | 33 + .../static-partition-pruning.md | 60 + .../when-to-use-hash-partitioning.md | 41 + .../when-to-use-list-partitioning.md | 33 + .../when-to-use-range-partitioning.md | 36 + .../plpgsql/1-1-plpgsql-overview.md | 24 + .../plpgsql/1-10-other-statements.md | 20 + .../developer-guide/plpgsql/1-11-cursors.md | 183 ++ .../plpgsql/1-12-retry-management.md | 26 + .../developer-guide/plpgsql/1-13-debugging.md | 174 ++ .../developer-guide/plpgsql/1-14-package.md | 21 + .../developer-guide/plpgsql/1-2-data-types.md | 10 + .../plpgsql/1-3-data-type-conversion.md | 42 + .../plpgsql/1-4-arrays-and-records.md | 198 ++ .../plpgsql/1-5-declare-syntax.md | 82 + .../plpgsql/1-6-basic-statements.md | 215 ++ .../plpgsql/1-7-dynamic-statements.md | 166 ++ .../plpgsql/1-8-control-statements.md | 651 ++++++ .../plpgsql/1-9-transaction-management.md | 408 ++++ .../basic-interfaces/PKG_SERVICE.md | 387 ++++ .../scheduled-jobs/pkg-service.md | 366 ++++ .../developer-guide/user-defined-functions.md | 16 + .../v3.1/faqs/application-development-faqs.md | 8 + .../faqs/deployment-and-maintenance-faqs.md | 332 +++ .../v3.1/faqs/high-availability-faqs.md | 28 + .../zh/docs-mogdb/v3.1/faqs/migration-faqs.md | 21 + .../zh/docs-mogdb/v3.1/faqs/product-faqs.md | 153 ++ .../zh/docs-mogdb/v3.1/faqs/upgrade-faqs.md | 8 + product/zh/docs-mogdb/v3.1/glossary.md | 161 ++ .../docker-installation.md | 452 ++++ .../environment-requirement.md | 73 + .../os-configuration.md | 292 +++ .../installation-guide/manual-installation.md | 383 ++++ .../om-installation/installation-overview.md | 16 + .../obtaining-installation-package.md | 48 + .../om-installation/simple-installation.md | 219 ++ .../om-installation/standard-installation.md | 692 ++++++ .../om-installation/uninstallation.md | 159 ++ .../om-installation/verifying-installation.md | 32 + .../ptk-based-installation.md | 197 ++ .../recommended-parameter-settings.md | 231 ++ .../v3.1/mogeaver/mogeaver-overview.md | 47 + .../v3.1/mogeaver/mogeaver-release-notes.md | 65 + product/zh/docs-mogdb/v3.1/overview.md | 181 ++ .../1-system/1-optimizing-os-parameters.md | 125 ++ .../2-optimizing-database-parameters.md | 69 + .../1-system/3-configuring-llvm.md | 86 + .../1-system/4-configuring-smp.md | 111 + .../2-sql/1-query-execution-process.md | 79 + ...-introduction-to-the-sql-execution-plan.md | 142 ++ .../2-sql/3-tuning-process.md | 39 + .../2-sql/4-updating-statistics.md | 58 + ...iewing-and-modifying-a-table-definition.md | 73 + .../6-typical-sql-optimization-methods.md | 722 +++++++ ...-experience-in-rewriting-sql-statements.md | 63 + ...etting-key-parameters-during-sql-tuning.md | 22 + .../2-sql/9-hint-based-tuning.md | 816 +++++++ .../performance-tuning/3-wdr/wdr-report.md | 385 ++++ .../3-wdr/wdr-snapshot-schema.md | 258 +++ .../TPCC-performance-tuning-guide.md | 780 +++++++ .../tuning-with-vector-engine.md | 59 + .../container-based-installation.md | 204 ++ .../installation-on-a-single-node.md | 192 ++ .../use-cli-to-access-mogdb/gsql.md | 216 ++ .../use-cli-to-access-mogdb/pgcli.md | 85 + .../datastudio.md | 112 + .../use-gui-tools-to-access-mogdb/dbeaver.md | 64 + .../mogeaver-usage.md | 60 + ...-configures-mogdb-data-source-reference.md | 175 ++ ...-configures-mogdb-data-source-reference.md | 210 ++ .../adonet.md | 14 + .../c-cpp.md | 15 + .../go.md | 14 + .../java.md | 14 + .../nodejs.md | 14 + .../python.md | 18 + .../rust.md | 14 + .../v3.1/quick-start/mogdb-playground.md | 46 + .../zh/docs-mogdb/v3.1/quick-start/mogila.md | 408 ++++ .../1-GAUSS-00001-GAUSS-00100.md | 828 ++++++++ .../10-GAUSS-00901-GAUSS-01000.md | 756 +++++++ .../11-GAUSS-01001-GAUSS-01100.md | 812 +++++++ .../12-GAUSS-01101-GAUSS-01200.md | 772 +++++++ .../13-GAUSS-01201-GAUSS-01300.md | 814 +++++++ .../14-GAUSS-01301-GAUSS-01400.md | 748 +++++++ .../15-GAUSS-01401-GAUSS-01500.md | 820 +++++++ .../16-GAUSS-01501-GAUSS-01600.md | 644 ++++++ .../17-GAUSS-01601-GAUSS-01700.md | 732 +++++++ .../18-GAUSS-01701-GAUSS-01800.md | 750 +++++++ .../19-GAUSS-01801-GAUSS-01900.md | 740 +++++++ .../2-GAUSS-00101-GAUSS-00200.md | 836 ++++++++ .../20-GAUSS-01901-GAUSS-02000.md | 614 ++++++ .../21-GAUSS-02001-GAUSS-02100.md | 376 ++++ .../22-GAUSS-02101-GAUSS-02200.md | 580 +++++ .../23-GAUSS-02201-GAUSS-02300.md | 556 +++++ .../24-GAUSS-02301-GAUSS-02400.md | 759 +++++++ .../25-GAUSS-02401-GAUSS-02500.md | 708 +++++++ .../26-GAUSS-02501-GAUSS-02600.md | 772 +++++++ .../27-GAUSS-02601-GAUSS-02700.md | 764 +++++++ .../28-GAUSS-02701-GAUSS-02800.md | 732 +++++++ .../29-GAUSS-02801-GAUSS-02900.md | 780 +++++++ .../3-GAUSS-00201-GAUSS-00300.md | 748 +++++++ .../30-GAUSS-02901-GAUSS-03000.md | 780 +++++++ .../31-GAUSS-03001-GAUSS-03100.md | 812 +++++++ .../32-GAUSS-03101-GAUSS-03200.md | 828 ++++++++ .../33-GAUSS-03201-GAUSS-03300.md | 820 +++++++ .../34-GAUSS-03301-GAUSS-03400.md | 828 ++++++++ .../35-GAUSS-03401-GAUSS-03500.md | 668 ++++++ .../36-GAUSS-03501-GAUSS-03600.md | 700 ++++++ .../37-GAUSS-03601-GAUSS-03700.md | 748 +++++++ .../38-GAUSS-03701-GAUSS-03800.md | 700 ++++++ .../39-GAUSS-03801-GAUSS-03900.md | 644 ++++++ .../4-GAUSS-00301-GAUSS-00400.md | 804 +++++++ .../40-GAUSS-03901-GAUSS-04000.md | 644 ++++++ .../41-GAUSS-04001-GAUSS-04100.md | 724 +++++++ .../42-GAUSS-04101-GAUSS-04200.md | 478 +++++ .../43-GAUSS-04201-GAUSS-04300.md | 692 ++++++ .../44-GAUSS-04301-GAUSS-04400.md | 444 ++++ .../45-GAUSS-04401-GAUSS-04500.md | 457 ++++ .../46-GAUSS-04501-GAUSS-04600.md | 644 ++++++ .../47-GAUSS-04601-GAUSS-04700.md | 614 ++++++ .../48-GAUSS-04701-GAUSS-04800.md | 559 +++++ .../49-GAUSS-04801-GAUSS-04900.md | 844 ++++++++ .../5-GAUSS-00401-GAUSS-00500.md | 692 ++++++ .../50-GAUSS-04901-GAUSS-05000.md | 860 ++++++++ .../51-GAUSS-05001-GAUSS-05100.md | 868 ++++++++ .../52-GAUSS-05101-GAUSS-05200.md | 604 ++++++ .../53-GAUSS-05201-GAUSS-05300.md | 868 ++++++++ .../54-GAUSS-05301-GAUSS-05400.md | 860 ++++++++ .../55-GAUSS-05401-GAUSS-05500.md | 860 ++++++++ .../56-GAUSS-05501-GAUSS-05600.md | 868 ++++++++ .../57-GAUSS-05601-GAUSS-05700.md | 868 ++++++++ .../58-GAUSS-05701-GAUSS-05800.md | 868 ++++++++ .../59-GAUSS-05801-GAUSS-05900.md | 698 ++++++ .../6-GAUSS-00501-GAUSS-00600.md | 724 +++++++ .../60-GAUSS-05901-GAUSS-06000.md | 764 +++++++ .../61-GAUSS-06001-GAUSS-06100.md | 852 ++++++++ .../62-GAUSS-06101-GAUSS-06200.md | 860 ++++++++ .../63-GAUSS-06201-GAUSS-06300.md | 924 ++++++++ .../64-GAUSS-06301-GAUSS-06400.md | 860 ++++++++ .../65-GAUSS-06401-GAUSS-06500.md | 788 +++++++ .../66-GAUSS-06501-GAUSS-06600.md | 868 ++++++++ .../67-GAUSS-06601-GAUSS-06700.md | 868 ++++++++ .../68-GAUSS-06701-GAUSS-06800.md | 868 ++++++++ .../69-GAUSS-06801-GAUSS-06900.md | 868 ++++++++ .../7-GAUSS-00601-GAUSS-00700.md | 748 +++++++ .../70-GAUSS-06901-GAUSS-07000.md | 868 ++++++++ .../71-GAUSS-07001-GAUSS-07100.md | 868 ++++++++ .../72-GAUSS-07101-GAUSS-07200.md | 868 ++++++++ .../73-GAUSS-07201-GAUSS-07300.md | 868 ++++++++ .../74-GAUSS-07301-GAUSS-07400.md | 868 ++++++++ .../75-GAUSS-07401-GAUSS-07480.md | 632 ++++++ .../76-GAUSS-50000-GAUSS-50999.md | 1100 ++++++++++ .../77-GAUSS-51000-GAUSS-51999.md | 1252 +++++++++++ .../78-GAUSS-52000-GAUSS-52999.md | 914 ++++++++ .../79-GAUSS-53000-GAUSS-53699.md | 954 +++++++++ .../8-GAUSS-00701-GAUSS-00800.md | 764 +++++++ .../9-GAUSS-00801-GAUSS-00900.md | 700 ++++++ .../description-of-sql-error-codes.md | 396 ++++ .../third-party-library-error-codes.md | 29 + .../kernel-error-message.md | 1328 ++++++++++++ .../1-logical-operators.md | 26 + .../10-geometric-functions-and-operators.md | 948 +++++++++ ...network-address-functions-and-operators.md | 456 ++++ .../12-text-search-functions-and-operators.md | 535 +++++ .../13-json-functions.md | 783 +++++++ .../13.1-hll-functions-and-operators.md | 894 ++++++++ .../14-sequence-functions.md | 133 ++ .../15-array-functions-and-operators.md | 614 ++++++ .../16-range-functions-and-operators.md | 435 ++++ .../17-aggregate-functions.md | 823 +++++++ .../18-window-functions.md | 650 ++++++ .../19-security-functions.md | 273 +++ .../2-comparison-operators.md | 27 + .../20-encrypted-equality-functions.md | 187 ++ .../20.1-ledger-database-functions.md | 96 + .../21-set-returning-functions.md | 131 ++ .../22-conditional-expressions-functions.md | 175 ++ .../23-system-information-functions.md | 1834 ++++++++++++++++ .../1-configuration-settings-functions.md | 62 + .../10-undo-system-functions.md | 89 + .../2-universal-file-access-functions.md | 148 ++ .../3-server-signal-functions.md | 66 + ...ackup-and-restoration-control-functions.md | 256 +++ .../5-snapshot-synchronization-functions.md | 24 + .../6-database-object-functions.md | 438 ++++ .../7-advisory-lock-functions.md | 244 +++ .../8-logical-replication-functions.md | 597 ++++++ .../9-other-functions.md | 674 ++++++ .../9.1-segment-page-storage-functions.md | 113 + .../25-statistics-information-functions.md | 1847 ++++++++++++++++ .../26-trigger-functions.md | 55 + .../27-global-temporary-table-functions.md | 132 ++ .../27.1-hash-function.md | 595 ++++++ .../27.2-prompt-message-function.md | 21 + .../28-ai-feature-functions.md | 200 ++ .../28.1-fault-injection-system-function.md | 20 + .../29-other-system-functions.md | 838 ++++++++ .../29.1-dynamic-data-masking-functions.md | 60 + ...cter-processing-functions-and-operators.md | 1883 +++++++++++++++++ .../30-internal-functions.md | 204 ++ .../31-obsolete-functions.md | 18 + .../32-global-syscache-feature-functions.md | 99 + ...a-damage-detection-and-repair-functions.md | 207 ++ ...4-binary-string-functions-and-operators.md | 210 ++ .../5-bit-string-functions-and-operators.md | 155 ++ .../6-mode-matching-operators.md | 230 ++ .../7-mathematical-functions-and-operators.md | 1232 +++++++++++ ...time-processing-functions-and-operators.md | 1390 ++++++++++++ .../9-type-conversion-functions.md | 1418 +++++++++++++ .../guc-parameters/1-guc-parameter-usage.md | 18 + .../1-logging-destination.md | 174 ++ .../2-logging-time.md | 119 ++ .../3-logging-content.md | 341 +++ .../4-using-csv-log-output.md | 88 + .../guc-parameters/11-alarm-detection.md | 73 + .../1-query-and-index-statistics-collector.md | 138 ++ .../2-performance-statistics.md | 35 + .../guc-parameters/13-load-management.md | 409 ++++ .../guc-parameters/14-automatic-vacuuming.md | 189 ++ .../1-statement-behavior.md | 245 +++ .../2-zone-and-formatting.md | 190 ++ .../3-other-default-parameters.md | 54 + .../guc-parameters/16-lock-management.md | 154 ++ .../1-compatibility-with-earlier-versions.md | 133 ++ .../2-platform-and-client-compatibility.md | 177 ++ .../guc-parameters/18-fault-tolerance.md | 119 ++ .../19-connection-pool-parameters.md | 47 + .../guc-parameters/2-file-location.md | 68 + .../guc-parameters/20-MogDB-transaction.md | 151 ++ .../guc-parameters/21-developer-options.md | 318 +++ .../22-auditing/1-audit-switch.md | 125 ++ .../2-user-and-permission-audit.md | 83 + .../22-auditing/3-operation-audit.md | 187 ++ .../guc-parameters/23-upgrade-parameters.md | 47 + .../24-miscellaneous-parameters.md | 208 ++ .../guc-parameters/25-wait-events.md | 23 + .../guc-parameters/26-query.md | 171 ++ .../27-system-performance-snapshot.md | 124 ++ .../27.1-security-configuration.md | 84 + .../29-global-temporary-table.md | 31 + .../guc-parameters/29.1-HyperLogLog.md | 104 + .../1-connection-settings.md | 199 ++ .../2-security-and-authentication.md | 403 ++++ .../3-communication-library-parameters.md | 87 + .../guc-parameters/30-appendix.md | 30 + .../guc-parameters/31-scheduled-task.md | 42 + .../guc-parameters/32-thread-pool.md | 38 + .../33-user-defined-functions.md | 54 + .../34-backup-and-restoration.md | 46 + .../reference-guide/guc-parameters/35-undo.md | 28 + .../36-DCF-parameters-settings.md | 362 ++++ .../guc-parameters/37-flashback.md | 64 + .../guc-parameters/38-rollback-parameters.md | 18 + .../guc-parameters/39-reserved-parameters.md | 30 + .../4-resource-consumption/1-memory.md | 337 +++ .../4-resource-consumption/2-disk-space.md | 35 + .../3-kernel-resource-usage.md | 41 + .../4-cost-based-vacuum-delay.md | 76 + .../5-background-writer.md | 152 ++ .../6-asynchronous-io-operations.md | 151 ++ .../guc-parameters/40-AI-features.md | 64 + .../6-write-ahead-log/1-settings.md | 294 +++ .../6-write-ahead-log/2-checkpoints.md | 129 ++ .../6-write-ahead-log/3-log-replay.md | 110 + .../6-write-ahead-log/4-archiving.md | 97 + .../7-ha-replication/1-sending-server.md | 153 ++ .../7-ha-replication/2-primary-server.md | 248 +++ .../7-ha-replication/3-standby-server.md | 146 ++ .../reference-guide/guc-parameters/8-mot.md | 72 + .../1-optimizer-method-configuration.md | 375 ++++ .../2-optimizer-cost-constants.md | 95 + .../3-genetic-query-optimizer.md | 112 + .../4-other-optimizer-options.md | 716 +++++++ .../introduction-to-query-planning.md | 17 + .../guc-parameters/SQL-mode.md | 38 + .../guc-parameters/cm-parameters/cm_agent.md | 314 +++ .../guc-parameters/cm-parameters/cm_server.md | 391 ++++ .../global-syscache-parameters.md | 43 + .../guc-parameters/guc-parameter-list.md | 702 ++++++ .../oracle-plugins/dblink-user-guide.md | 65 + .../reference-guide/oracle-plugins/dolphin.md | 647 ++++++ .../oracle-plugins/orafce-user-guide.md | 252 +++ .../oracle-plugins/pg_bulkload-user-guide.md | 87 + .../oracle-plugins/pg_prewarm-user-guide.md | 89 + .../oracle-plugins/pg_repack-user-guide.md | 91 + .../oracle-plugins/pg_trgm-user-guide.md | 60 + .../postgis-extension/postgis-overview.md | 24 + .../postgis-support-and-constraints.md | 57 + .../postgis-extension/using-postgis.md | 80 + .../oracle-plugins/wal2json-user-guide.md | 109 + .../reference-guide/oracle-plugins/whale.md | 223 ++ .../DB4AI-schema/DB4AI.ARCHIVE_SNAPSHOT.md | 18 + .../DB4AI-schema/DB4AI.CREATE_SNAPSHOT.md | 21 + .../DB4AI.CREATE_SNAPSHOT_INTERNAL.md | 21 + .../DB4AI.MANAGE_SNAPSHOT_INTERNAL.md | 19 + .../DB4AI-schema/DB4AI.PREPARE_SNAPSHOT.md | 21 + .../DB4AI.PREPARE_SNAPSHOT_INTERNAL.md | 27 + .../DB4AI-schema/DB4AI.PUBLISH_SNAPSHOT.md | 18 + .../DB4AI-schema/DB4AI.PURGE_SNAPSHOT.md | 18 + .../DB4AI.PURGE_SNAPSHOT_INTERNAL.md | 17 + .../DB4AI-schema/DB4AI.SAMPLE_SNAPSHOT.md | 22 + .../schema/DB4AI-schema/DB4AI.SNAPSHOT.md | 28 + .../DB4AI-schema/overview-of-DB4AI-schema.md | 10 + .../schema/DBE_PERF/DBE_PERF_overview.md | 40 + .../cache-io/GLOBAL_STATIO_ALL_INDEXES.md | 23 + .../cache-io/GLOBAL_STATIO_ALL_SEQUENCES.md | 21 + .../cache-io/GLOBAL_STATIO_ALL_TABLES.md | 27 + .../cache-io/GLOBAL_STATIO_SYS_INDEXES.md | 23 + .../cache-io/GLOBAL_STATIO_SYS_SEQUENCES.md | 21 + .../cache-io/GLOBAL_STATIO_SYS_TABLES.md | 27 + .../cache-io/GLOBAL_STATIO_USER_INDEXES.md | 23 + .../cache-io/GLOBAL_STATIO_USER_SEQUENCES.md | 21 + .../cache-io/GLOBAL_STATIO_USER_TABLES.md | 27 + .../DBE_PERF/cache-io/GLOBAL_STAT_DB_CU.md | 20 + .../cache-io/GLOBAL_STAT_SESSION_CU.md | 18 + .../DBE_PERF/cache-io/STATIO_ALL_INDEXES.md | 22 + .../DBE_PERF/cache-io/STATIO_ALL_SEQUENCES.md | 20 + .../DBE_PERF/cache-io/STATIO_ALL_TABLES.md | 26 + .../DBE_PERF/cache-io/STATIO_SYS_INDEXES.md | 22 + .../DBE_PERF/cache-io/STATIO_SYS_SEQUENCES.md | 20 + .../DBE_PERF/cache-io/STATIO_SYS_TABLES.md | 26 + .../DBE_PERF/cache-io/STATIO_USER_INDEXES.md | 22 + .../cache-io/STATIO_USER_SEQUENCES.md | 20 + .../DBE_PERF/cache-io/STATIO_USER_TABLES.md | 26 + .../cache-io/SUMMARY_STATIO_ALL_INDEXES.md | 18 + .../cache-io/SUMMARY_STATIO_ALL_SEQUENCES.md | 19 + .../cache-io/SUMMARY_STATIO_ALL_TABLES.md | 25 + .../cache-io/SUMMARY_STATIO_SYS_INDEXES.md | 20 + .../cache-io/SUMMARY_STATIO_SYS_SEQUENCES.md | 19 + .../cache-io/SUMMARY_STATIO_SYS_TABLES.md | 25 + .../cache-io/SUMMARY_STATIO_USER_INDEXES.md | 20 + .../cache-io/SUMMARY_STATIO_USER_SEQUENCES.md | 19 + .../cache-io/SUMMARY_STATIO_USER_TABLES.md | 25 + .../DBE_PERF/configuration/CONFIG_SETTINGS.md | 31 + .../configuration/GLOBAL_CONFIG_SETTINGS.md | 32 + .../schema/DBE_PERF/file/FILE_IOSTAT.md | 28 + .../schema/DBE_PERF/file/FILE_REDO_IOSTAT.md | 22 + .../DBE_PERF/file/GLOBAL_FILE_IOSTAT.md | 29 + .../DBE_PERF/file/GLOBAL_FILE_REDO_IOSTAT.md | 23 + .../schema/DBE_PERF/file/GLOBAL_REL_IOSTAT.md | 20 + .../schema/DBE_PERF/file/LOCAL_REL_IOSTAT.md | 19 + .../DBE_PERF/file/SUMMARY_FILE_IOSTAT.md | 28 + .../DBE_PERF/file/SUMMARY_FILE_REDO_IOSTAT.md | 22 + .../DBE_PERF/file/SUMMARY_REL_IOSTAT.md | 19 + .../GLOBAL_PLANCACHE_CLEAN.md | 10 + .../GLOBAL_PLANCACHE_STATUS.md | 23 + .../global-plancache-overview.md | 10 + .../DBE_PERF/instance/GLOBAL_INSTANCE_TIME.md | 19 + .../schema/DBE_PERF/instance/INSTANCE_TIME.md | 29 + .../schema/DBE_PERF/lock/GLOBAL_LOCKS.md | 29 + .../schema/DBE_PERF/lock/LOCKS.md | 34 + .../memory/GLOBAL_MEMORY_NODE_DETAIL.md | 18 + .../memory/GLOBAL_SHARED_MEMORY_DETAIL.md | 22 + .../memory/GS_SHARED_MEMORY_DETAIL.md | 21 + .../DBE_PERF/memory/MEMORY_NODE_DETAIL.md | 18 + .../object/GLOBAL_STAT_ALL_INDEXES.md | 24 + .../DBE_PERF/object/GLOBAL_STAT_ALL_TABLES.md | 37 + .../DBE_PERF/object/GLOBAL_STAT_BAD_BLOCK.md | 23 + .../DBE_PERF/object/GLOBAL_STAT_DATABASE.md | 35 + .../object/GLOBAL_STAT_DATABASE_CONFLICTS.md | 23 + .../object/GLOBAL_STAT_SYS_INDEXES.md | 24 + .../DBE_PERF/object/GLOBAL_STAT_SYS_TABLES.md | 37 + .../object/GLOBAL_STAT_USER_FUNCTIONS.md | 22 + .../object/GLOBAL_STAT_USER_INDEXES.md | 24 + .../object/GLOBAL_STAT_USER_TABLES.md | 37 + .../object/GLOBAL_STAT_XACT_ALL_TABLES.md | 27 + .../object/GLOBAL_STAT_XACT_SYS_TABLES.md | 27 + .../object/GLOBAL_STAT_XACT_USER_FUNCTIONS.md | 22 + .../object/GLOBAL_STAT_XACT_USER_TABLES.md | 27 + .../DBE_PERF/object/STAT_ALL_INDEXES.md | 23 + .../schema/DBE_PERF/object/STAT_ALL_TABLES.md | 36 + .../schema/DBE_PERF/object/STAT_BAD_BLOCK.md | 24 + .../schema/DBE_PERF/object/STAT_DATABASE.md | 34 + .../object/STAT_DATABASE_CONFLICTS.md | 22 + .../DBE_PERF/object/STAT_SYS_INDEXES.md | 23 + .../schema/DBE_PERF/object/STAT_SYS_TABLES.md | 36 + .../DBE_PERF/object/STAT_USER_FUNCTIONS.md | 21 + .../DBE_PERF/object/STAT_USER_INDEXES.md | 23 + .../DBE_PERF/object/STAT_USER_TABLES.md | 36 + .../DBE_PERF/object/STAT_XACT_ALL_TABLES.md | 26 + .../DBE_PERF/object/STAT_XACT_SYS_TABLES.md | 26 + .../object/STAT_XACT_USER_FUNCTIONS.md | 21 + .../DBE_PERF/object/STAT_XACT_USER_TABLES.md | 26 + .../object/SUMMARY_STAT_ALL_INDEXES.md | 21 + .../object/SUMMARY_STAT_ALL_TABLES.md | 35 + .../DBE_PERF/object/SUMMARY_STAT_BAD_BLOCK.md | 22 + .../DBE_PERF/object/SUMMARY_STAT_DATABASE.md | 33 + .../object/SUMMARY_STAT_DATABASE_CONFLICTS.md | 21 + .../object/SUMMARY_STAT_SYS_INDEXES.md | 21 + .../object/SUMMARY_STAT_SYS_TABLES.md | 35 + .../object/SUMMARY_STAT_USER_FUNCTIONS.md | 20 + .../object/SUMMARY_STAT_USER_INDEXES.md | 21 + .../object/SUMMARY_STAT_USER_TABLES.md | 35 + .../object/SUMMARY_STAT_XACT_ALL_TABLES.md | 25 + .../object/SUMMARY_STAT_XACT_SYS_TABLES.md | 25 + .../SUMMARY_STAT_XACT_USER_FUNCTIONS.md | 20 + .../object/SUMMARY_STAT_XACT_USER_TABLES.md | 25 + .../operator/GLOBAL_OPERATOR_HISTORY.md | 37 + .../operator/GLOBAL_OPERATOR_HISTORY_TABLE.md | 10 + .../operator/GLOBAL_OPERATOR_RUNTIME.md | 38 + .../DBE_PERF/operator/OPERATOR_HISTORY.md | 10 + .../operator/OPERATOR_HISTORY_TABLE.md | 37 + .../DBE_PERF/operator/OPERATOR_RUNTIME.md | 38 + .../schema/DBE_PERF/os/GLOBAL_OS_RUNTIME.md | 21 + .../schema/DBE_PERF/os/GLOBAL_OS_THREADS.md | 20 + .../schema/DBE_PERF/os/OS_RUNTIME.md | 20 + .../schema/DBE_PERF/os/OS_THREADS.md | 20 + .../query/GLOBAL_STATEMENT_COMPLEX_HISTORY.md | 83 + .../GLOBAL_STATEMENT_COMPLEX_HISTORY_TABLE.md | 10 + .../query/GLOBAL_STATEMENT_COMPLEX_RUNTIME.md | 63 + .../DBE_PERF/query/GLOBAL_STATEMENT_COUNT.md | 41 + .../schema/DBE_PERF/query/STATEMENT.md | 56 + .../query/STATEMENT_COMPLEX_HISTORY.md | 10 + .../query/STATEMENT_COMPLEX_HISTORY_TABLE.md | 10 + .../query/STATEMENT_COMPLEX_RUNTIME.md | 63 + .../schema/DBE_PERF/query/STATEMENT_COUNT.md | 44 + .../DBE_PERF/query/STATEMENT_HISTORY_1.md | 67 + .../STATEMENT_RESPONSETIME_PERCENTILE.md | 17 + .../query/STATEMENT_USER_COMPLEX_HISTORY.md | 10 + .../STATEMENT_WLMSTAT_COMPLEX_RUNTIME.md | 38 + .../DBE_PERF/query/SUMMARY_STATEMENT.md | 56 + .../DBE_PERF/query/SUMMARY_STATEMENT_COUNT.md | 40 + .../schema/DBE_PERF/rto/global_rto_status.md | 17 + .../session-thread/GLOBAL_SESSION_MEMORY.md | 20 + .../GLOBAL_SESSION_MEMORY_DETAIL.md | 24 + .../session-thread/GLOBAL_SESSION_STAT.md | 21 + .../GLOBAL_SESSION_STAT_ACTIVITY.md | 37 + .../session-thread/GLOBAL_SESSION_TIME.md | 20 + .../GLOBAL_THREADPOOL_STATUS.md | 10 + .../GLOBAL_THREAD_WAIT_STATUS.md | 31 + .../session-thread/LOCAL_ACTIVE_SESSION.md | 44 + .../session-thread/LOCAL_THREADPOOL_STATUS.md | 24 + .../session-thread/SESSION_CPU_RUNTIME.md | 25 + .../DBE_PERF/session-thread/SESSION_MEMORY.md | 19 + .../session-thread/SESSION_MEMORY_DETAIL.md | 23 + .../session-thread/SESSION_MEMORY_RUNTIME.md | 25 + .../DBE_PERF/session-thread/SESSION_STAT.md | 20 + .../session-thread/SESSION_STAT_ACTIVITY.md | 36 + .../DBE_PERF/session-thread/SESSION_TIME.md | 19 + .../STATEMENT_IOSTAT_COMPLEX_RUNTIME.md | 24 + .../session-thread/THREAD_WAIT_STATUS.md | 27 + .../GLOBAL_TRANSACTIONS_PREPARED_XACTS.md | 20 + .../GLOBAL_TRANSACTIONS_RUNNING_XACTS.md | 25 + .../SUMMARY_TRANSACTIONS_PREPARED_XACTS.md | 20 + .../SUMMARY_TRANSACTIONS_RUNNING_XACTS.md | 25 + .../TRANSACTIONS_PREPARED_XACTS.md | 20 + .../transaction/TRANSACTIONS_RUNNING_XACTS.md | 25 + .../schema/DBE_PERF/utility/BGWRITER_STAT.md | 26 + .../DBE_PERF/utility/CLASS_VITAL_INFO.md | 19 + .../DBE_PERF/utility/GLOBAL_BGWRITER_STAT.md | 27 + .../utility/GLOBAL_CANDIDATE_STATUS.md | 22 + .../DBE_PERF/utility/GLOBAL_CKPT_STATUS.md | 22 + .../utility/GLOBAL_DOUBLE_WRITE_STATUS.md | 27 + .../utility/GLOBAL_GET_BGWRITER_STATUS.md | 21 + .../utility/GLOBAL_PAGEWRITER_STATUS.md | 23 + .../utility/GLOBAL_RECORD_RESET_TIME.md | 17 + .../utility/GLOBAL_RECOVERY_STATUS.md | 24 + .../DBE_PERF/utility/GLOBAL_REDO_STATUS.md | 38 + .../utility/GLOBAL_REPLICATION_SLOTS.md | 26 + .../utility/GLOBAL_REPLICATION_STAT.md | 31 + .../utility/GLOBAL_SINGLE_FLUSH_DW_STATUS.md | 21 + .../DBE_PERF/utility/REPLICATION_SLOTS.md | 25 + .../DBE_PERF/utility/REPLICATION_STAT.md | 30 + .../DBE_PERF/utility/SUMMARY_USER_LOGIN.md | 20 + .../schema/DBE_PERF/utility/USER_LOGIN.md | 20 + .../wait-events/GLOBAL_WAIT_EVENTS.md | 25 + .../DBE_PERF/wait-events/WAIT_EVENTS.md | 25 + .../WLM_USER_RESOURCE_CONFIG.md | 25 + .../WLM_USER_RESOURCE_RUNTIME.md | 26 + .../workload/GLOBAL_USER_TRANSACTION.md | 29 + .../workload/GLOBAL_WORKLOAD_TRANSACTION.md | 29 + .../workload/SUMMARY_WORKLOAD_SQL_COUNT.md | 24 + .../SUMMARY_WORKLOAD_SQL_ELAPSE_TIME.md | 33 + .../workload/SUMMARY_WORKLOAD_TRANSACTION.md | 28 + .../DBE_PERF/workload/USER_TRANSACTION.md | 28 + .../DBE_PERF/workload/WORKLOAD_SQL_COUNT.md | 23 + .../workload/WORKLOAD_SQL_ELAPSE_TIME.md | 32 + .../DBE_PERF/workload/WORKLOAD_TRANSACTION.md | 28 + .../DBE_PLDEBUGGER.abort.md | 23 + .../DBE_PLDEBUGGER.add_breakpoint.md | 18 + .../DBE_PLDEBUGGER.attach.md | 23 + .../DBE_PLDEBUGGER.backtrace.md | 20 + .../DBE_PLDEBUGGER.continue.md | 26 + .../DBE_PLDEBUGGER.delete_breakpoint.md | 17 + .../DBE_PLDEBUGGER.disable_breakpoint.md | 17 + .../DBE_PLDEBUGGER.enable_breakpoint.md | 17 + .../DBE_PLDEBUGGER.finish.md | 19 + .../DBE_PLDEBUGGER.info_breakpoints.md | 20 + .../DBE_PLDEBUGGER.info_code.md | 19 + .../DBE_PLDEBUGGER.info_locals.md | 21 + .../DBE_PLDEBUGGER.local_debug_server_info.md | 18 + .../DBE_PLDEBUGGER.next.md | 19 + .../DBE_PLDEBUGGER.print_var.md | 22 + .../DBE_PLDEBUGGER.set_var.md | 18 + .../DBE_PLDEBUGGER.step.md | 19 + .../DBE_PLDEBUGGER.turn_off.md | 24 + .../DBE_PLDEBUGGER.turn_on.md | 25 + .../overview-of-DBE_PLDEBUGGER-schema.md | 191 ++ .../DBE_PLDEVELOPER.gs_errors.md | 24 + .../DBE_PLDEVELOPER.gs_source.md | 24 + .../overview-of-DBE_PLDEVELOPER.md | 10 + .../1-information-schema-overview.md | 18 + .../2-_PG_FOREIGN_DATA_WRAPPERS.md | 22 + .../3-_PG_FOREIGN_SERVERS.md | 24 + .../4-_PG_FOREIGN_TABLE_COLUMNS.md | 19 + .../5-_PG_FOREIGN_TABLES.md | 22 + .../information-schema/6-_PG_USER_MAPPINGS.md | 22 + .../7-INFORMATION_SCHEMA_CATALOG_NAME.md | 16 + .../sql-reference/1-mogdb-sql.md | 37 + .../sql-reference/10-dml-syntax-overview.md | 51 + .../sql-reference/11-dcl-syntax-overview.md | 50 + .../1-gin-indexes/1-introduction.md | 16 + .../1-gin-indexes/2-scalability.md | 50 + .../1-gin-indexes/3-implementation.md | 24 + .../1-gin-indexes/4-gin-tips-and-tricks.md | 26 + .../13-appendix/2-extended-functions.md | 36 + .../13-appendix/3-extended-syntax.md | 52 + .../sql-reference/2-keywords.md | 831 ++++++++ .../sql-reference/3-constant-and-macro.md | 24 + .../4-expressions/1-simple-expressions.md | 132 ++ .../4-expressions/2-condition-expressions.md | 225 ++ .../4-expressions/3-subquery-expressions.md | 144 ++ .../4-expressions/4-array-expressions.md | 93 + .../4-expressions/5-row-expressions.md | 28 + .../1-type-conversion-overview.md | 52 + .../5-type-conversion/2-operators.md | 92 + .../5-type-conversion/3-functions.md | 103 + .../5-type-conversion/4-value-storage.md | 36 + .../5-union-case-and-related-constructs.md | 205 ++ .../1-introduction/1-full-text-retrieval.md | 38 + .../1-introduction/2-what-is-a-document.md | 33 + .../1-introduction/3-basic-text-matching.md | 56 + .../1-introduction/4-configurations.md | 21 + .../1-searching-a-table.md | 91 + .../2-creating-an-index.md | 65 + .../3-constraints-on-index-use.md | 44 + .../1-parsing-documents.md | 52 + .../2-parsing-queries.md | 74 + .../3-ranking-search-results.md | 108 + .../4-highlighting-results.md | 66 + .../1-manipulating-tsvector.md | 31 + .../2-manipulating-queries.md | 52 + .../3-rewriting-queries.md | 68 + .../4-gathering-document-statistics.md | 50 + .../6-full-text-search/5-parser.md | 108 + .../6-dictionaries/1-dictionaries-overview.md | 36 + .../6-dictionaries/2-stop-words.md | 33 + .../6-dictionaries/3-simple-dictionary.md | 64 + .../6-dictionaries/4-synonym-dictionary.md | 116 + .../6-dictionaries/5-thesaurus-dictionary.md | 92 + .../6-dictionaries/6-ispell-dictionary.md | 49 + .../6-dictionaries/7-snowball-dictionary.md | 14 + .../7-configuration-examples.md | 116 + .../1-testing-a-configuration.md | 65 + .../2-testing-a-parser.md | 74 + .../3-testing-a-dictionary.md | 29 + .../6-full-text-search/9-limitations.md | 16 + .../sql-reference/7-system-operation.md | 38 + .../8-controlling-transactions.md | 29 + .../sql-reference/9-ddl-syntax-overview.md | 228 ++ .../v3.1/reference-guide/sql-syntax/ABORT.md | 76 + .../sql-syntax/ALTER-AGGREGATE.md | 76 + .../sql-syntax/ALTER-AUDIT-POLICY.md | 101 + .../sql-syntax/ALTER-DATA-SOURCE.md | 114 + .../sql-syntax/ALTER-DATABASE.md | 144 ++ .../sql-syntax/ALTER-DEFAULT-PRIVILEGES.md | 208 ++ .../sql-syntax/ALTER-DIRECTORY.md | 47 + .../sql-syntax/ALTER-EXTENSION.md | 155 ++ .../sql-syntax/ALTER-FOREIGN-TABLE.md | 118 ++ .../sql-syntax/ALTER-FUNCTION.md | 197 ++ .../sql-syntax/ALTER-GLOBAL-CONFIGURATION.md | 53 + .../reference-guide/sql-syntax/ALTER-GROUP.md | 60 + .../reference-guide/sql-syntax/ALTER-INDEX.md | 160 ++ .../sql-syntax/ALTER-LANGUAGE.md | 36 + .../sql-syntax/ALTER-LARGE-OBJECT.md | 41 + .../sql-syntax/ALTER-MASKING-POLICY.md | 140 ++ .../sql-syntax/ALTER-MATERIALIZED-VIEW.md | 79 + .../sql-syntax/ALTER-PACKAGE.md | 48 + .../sql-syntax/ALTER-PROCEDURE.md | 188 ++ .../sql-syntax/ALTER-PUBLICATION.md | 84 + .../sql-syntax/ALTER-RESOURCE-LABEL.md | 71 + .../sql-syntax/ALTER-RESOURCE-POOL.md | 117 + .../reference-guide/sql-syntax/ALTER-ROLE.md | 140 ++ .../ALTER-ROW-LEVEL-SECURITY-POLICY.md | 114 + .../reference-guide/sql-syntax/ALTER-RULE.md | 45 + .../sql-syntax/ALTER-SCHEMA.md | 91 + .../sql-syntax/ALTER-SEQUENCE.md | 86 + .../sql-syntax/ALTER-SERVER.md | 106 + .../sql-syntax/ALTER-SESSION.md | 90 + .../sql-syntax/ALTER-SUBSCRIPTION.md | 94 + .../sql-syntax/ALTER-SYNONYM.md | 62 + .../sql-syntax/ALTER-SYSTEM-KILL-SESSION.md | 55 + .../sql-syntax/ALTER-SYSTEM-SET.md | 79 + .../sql-syntax/ALTER-TABLE-PARTITION.md | 284 +++ .../sql-syntax/ALTER-TABLE-SUBPARTITION.md | 163 ++ .../reference-guide/sql-syntax/ALTER-TABLE.md | 461 ++++ .../sql-syntax/ALTER-TABLESPACE.md | 127 ++ .../ALTER-TEXT-SEARCH-CONFIGURATION.md | 180 ++ .../ALTER-TEXT-SEARCH-DICTIONARY.md | 105 + .../sql-syntax/ALTER-TRIGGER.md | 54 + .../reference-guide/sql-syntax/ALTER-TYPE.md | 177 ++ .../sql-syntax/ALTER-USER-MAPPING.md | 73 + .../reference-guide/sql-syntax/ALTER-USER.md | 123 ++ .../reference-guide/sql-syntax/ALTER-VIEW.md | 134 ++ .../sql-syntax/ANALYZE-ANALYSE.md | 192 ++ .../v3.1/reference-guide/sql-syntax/BEGIN.md | 62 + .../v3.1/reference-guide/sql-syntax/CALL.md | 84 + .../reference-guide/sql-syntax/CHECKPOINT.md | 36 + .../sql-syntax/CLEAN-CONNECTION.md | 76 + .../v3.1/reference-guide/sql-syntax/CLOSE.md | 45 + .../reference-guide/sql-syntax/CLUSTER.md | 128 ++ .../reference-guide/sql-syntax/COMMENT.md | 159 ++ .../reference-guide/sql-syntax/COMMIT-END.md | 72 + .../sql-syntax/COMMIT-PREPARED.md | 49 + .../reference-guide/sql-syntax/CONNECT-BY.md | 209 ++ .../v3.1/reference-guide/sql-syntax/COPY.md | 637 ++++++ .../sql-syntax/CREATE-AGGREGATE.md | 88 + .../sql-syntax/CREATE-AUDIT-POLICY.md | 108 + .../reference-guide/sql-syntax/CREATE-CAST.md | 90 + .../sql-syntax/CREATE-CLIENT-MASTER-KEY.md | 61 + .../CREATE-COLUMN-ENCRYPTION-KEY.md | 58 + .../sql-syntax/CREATE-DATA-SOURCE.md | 96 + .../sql-syntax/CREATE-DATABASE.md | 236 +++ .../sql-syntax/CREATE-DIRECTORY.md | 58 + .../sql-syntax/CREATE-EXTENSION.md | 59 + .../sql-syntax/CREATE-FOREIGN-TABLE.md | 146 ++ .../sql-syntax/CREATE-FUNCTION.md | 319 +++ .../sql-syntax/CREATE-GROUP.md | 66 + .../CREATE-INCREMENTAL-MATERIALIZED-VIEW.md | 71 + .../sql-syntax/CREATE-INDEX.md | 547 +++++ .../sql-syntax/CREATE-LANGUAGE.md | 71 + .../sql-syntax/CREATE-MASKING-POLICY.md | 111 + .../sql-syntax/CREATE-MATERIALIZED-VIEW.md | 77 + .../sql-syntax/CREATE-MODEL.md | 85 + .../sql-syntax/CREATE-OPERATOR.md | 117 + .../sql-syntax/CREATE-PACKAGE.md | 109 + .../sql-syntax/CREATE-PROCEDURE.md | 119 ++ .../sql-syntax/CREATE-PUBLICATION.md | 72 + .../sql-syntax/CREATE-RESOURCE-LABEL.md | 85 + .../sql-syntax/CREATE-RESOURCE-POOL.md | 136 ++ .../reference-guide/sql-syntax/CREATE-ROLE.md | 287 +++ .../CREATE-ROW-LEVEL-SECURITY-POLICY.md | 175 ++ .../reference-guide/sql-syntax/CREATE-RULE.md | 73 + .../sql-syntax/CREATE-SCHEMA.md | 89 + .../sql-syntax/CREATE-SEQUENCE.md | 147 ++ .../sql-syntax/CREATE-SERVER.md | 120 ++ .../sql-syntax/CREATE-SUBSCRIPTION.md | 108 + .../sql-syntax/CREATE-SYNONYM.md | 113 + .../sql-syntax/CREATE-TABLE-AS.md | 161 ++ .../sql-syntax/CREATE-TABLE-PARTITION.md | 960 +++++++++ .../sql-syntax/CREATE-TABLE-SUBPARTITION.md | 783 +++++++ .../sql-syntax/CREATE-TABLE.md | 1123 ++++++++++ .../sql-syntax/CREATE-TABLESPACE.md | 136 ++ .../CREATE-TEXT-SEARCH-CONFIGURATION.md | 96 + .../CREATE-TEXT-SEARCH-DICTIONARY.md | 152 ++ .../sql-syntax/CREATE-TRIGGER.md | 250 +++ .../reference-guide/sql-syntax/CREATE-TYPE.md | 298 +++ .../sql-syntax/CREATE-USER-MAPPING.md | 85 + .../reference-guide/sql-syntax/CREATE-USER.md | 122 ++ .../reference-guide/sql-syntax/CREATE-VIEW.md | 81 + .../CREATE-WEAK-PASSWORD-DICTIONARY.md | 54 + .../v3.1/reference-guide/sql-syntax/CURSOR.md | 70 + .../reference-guide/sql-syntax/DEALLOCATE.md | 38 + .../reference-guide/sql-syntax/DECLARE.md | 94 + .../v3.1/reference-guide/sql-syntax/DELETE.md | 122 ++ .../v3.1/reference-guide/sql-syntax/DO.md | 55 + .../sql-syntax/DROP-AGGREGATE.md | 56 + .../sql-syntax/DROP-AUDIT-POLICY.md | 38 + .../reference-guide/sql-syntax/DROP-CAST.md | 56 + .../sql-syntax/DROP-CLIENT-MASTER-KEY.md | 50 + .../sql-syntax/DROP-COLUMN-ENCRYPTION-KEY.md | 43 + .../sql-syntax/DROP-DATA-SOURCE.md | 57 + .../sql-syntax/DROP-DATABASE.md | 54 + .../sql-syntax/DROP-DIRECTORY.md | 44 + .../sql-syntax/DROP-EXTENSION.md | 51 + .../sql-syntax/DROP-FOREIGN-TABLE.md | 44 + .../sql-syntax/DROP-FUNCTION.md | 56 + .../sql-syntax/DROP-GLOBAL-CONFIGURATION.md | 27 + .../reference-guide/sql-syntax/DROP-GROUP.md | 32 + .../reference-guide/sql-syntax/DROP-INDEX.md | 56 + .../sql-syntax/DROP-LANGUAGE.md | 48 + .../sql-syntax/DROP-MASKING-POLICY.md | 44 + .../sql-syntax/DROP-MATERIALIZED-VIEW.md | 48 + .../reference-guide/sql-syntax/DROP-MODEL.md | 34 + .../sql-syntax/DROP-OPERATOR.md | 10 + .../reference-guide/sql-syntax/DROP-OWNED.md | 40 + .../sql-syntax/DROP-PACKAGE.md | 26 + .../sql-syntax/DROP-PROCEDURE.md | 38 + .../sql-syntax/DROP-PUBLICATION.md | 44 + .../sql-syntax/DROP-RESOURCE-LABEL.md | 44 + .../sql-syntax/DROP-RESOURCE-POOL.md | 44 + .../reference-guide/sql-syntax/DROP-ROLE.md | 42 + .../DROP-ROW-LEVEL-SECURITY-POLICY.md | 57 + .../reference-guide/sql-syntax/DROP-RULE.md | 47 + .../reference-guide/sql-syntax/DROP-SCHEMA.md | 51 + .../sql-syntax/DROP-SEQUENCE.md | 55 + .../reference-guide/sql-syntax/DROP-SERVER.md | 41 + .../sql-syntax/DROP-SUBSCRIPTION.md | 41 + .../sql-syntax/DROP-SYNONYM.md | 45 + .../reference-guide/sql-syntax/DROP-TABLE.md | 51 + .../sql-syntax/DROP-TABLESPACE.md | 52 + .../DROP-TEXT-SEARCH-CONFIGURATION.md | 48 + .../sql-syntax/DROP-TEXT-SEARCH-DICTIONARY.md | 57 + .../sql-syntax/DROP-TRIGGER.md | 53 + .../reference-guide/sql-syntax/DROP-TYPE.md | 48 + .../sql-syntax/DROP-USER-MAPPING.md | 38 + .../reference-guide/sql-syntax/DROP-USER.md | 59 + .../reference-guide/sql-syntax/DROP-VIEW.md | 47 + .../DROP-WEAK-PASSWORD-DICTIONARY.md | 34 + .../sql-syntax/EXECUTE-DIRECT.md | 83 + .../reference-guide/sql-syntax/EXECUTE.md | 59 + .../sql-syntax/EXPLAIN-PLAN.md | 84 + .../reference-guide/sql-syntax/EXPLAIN.md | 299 +++ .../v3.1/reference-guide/sql-syntax/FETCH.md | 218 ++ .../v3.1/reference-guide/sql-syntax/GRANT.md | 635 ++++++ .../v3.1/reference-guide/sql-syntax/INSERT.md | 192 ++ .../v3.1/reference-guide/sql-syntax/LOCK.md | 136 ++ .../reference-guide/sql-syntax/MERGE-INTO.md | 159 ++ .../v3.1/reference-guide/sql-syntax/MOVE.md | 81 + .../reference-guide/sql-syntax/PREDICT-BY.md | 47 + .../sql-syntax/PREPARE-TRANSACTION.md | 43 + .../reference-guide/sql-syntax/PREPARE.md | 46 + .../v3.1/reference-guide/sql-syntax/PURGE.md | 116 + .../sql-syntax/REASSIGN-OWNED.md | 39 + .../REFRESH-INCREMENTAL-MATERIALIZED-VIEW.md | 46 + .../sql-syntax/REFRESH-MATERIALIZED-VIEW.md | 50 + .../reference-guide/sql-syntax/REINDEX.md | 172 ++ .../sql-syntax/RELEASE-SAVEPOINT.md | 69 + .../v3.1/reference-guide/sql-syntax/RESET.md | 68 + .../v3.1/reference-guide/sql-syntax/REVOKE.md | 269 +++ .../sql-syntax/ROLLBACK-PREPARED.md | 34 + .../sql-syntax/ROLLBACK-TO-SAVEPOINT.md | 59 + .../reference-guide/sql-syntax/ROLLBACK.md | 44 + .../reference-guide/sql-syntax/SAVEPOINT.md | 98 + .../reference-guide/sql-syntax/SELECT-INTO.md | 100 + .../v3.1/reference-guide/sql-syntax/SELECT.md | 684 ++++++ .../sql-syntax/SET-CONSTRAINTS.md | 59 + .../reference-guide/sql-syntax/SET-ROLE.md | 74 + .../sql-syntax/SET-SESSION-AUTHORIZATION.md | 78 + .../sql-syntax/SET-TRANSACTION.md | 63 + .../v3.1/reference-guide/sql-syntax/SET.md | 122 ++ .../v3.1/reference-guide/sql-syntax/SHOW.md | 51 + .../reference-guide/sql-syntax/SHUTDOWN.md | 50 + .../reference-guide/sql-syntax/SNAPSHOT.md | 110 + .../sql-syntax/START-TRANSACTION.md | 88 + .../sql-syntax/TIMECAPSULE-TABLE.md | 128 ++ .../reference-guide/sql-syntax/TRUNCATE.md | 130 ++ .../v3.1/reference-guide/sql-syntax/UPDATE.md | 148 ++ .../v3.1/reference-guide/sql-syntax/VACUUM.md | 122 ++ .../v3.1/reference-guide/sql-syntax/VALUES.md | 67 + .../1-numeric-data-types.md | 263 +++ .../10-text-search-types.md | 168 ++ .../supported-data-types/11-uuid-type.md | 27 + .../supported-data-types/12-json-types.md | 146 ++ .../supported-data-types/13-HLL.md | 210 ++ .../supported-data-types/13.0-array-types.md | 466 ++++ .../supported-data-types/13.1-range.md | 163 ++ .../14-object-identifier-types.md | 90 + .../supported-data-types/15-pseudo-types.md | 65 + ...-types-supported-by-column-store-tables.md | 233 ++ .../supported-data-types/17-xml-type.md | 34 + ...8-data-type-used-by-the-ledger-database.md | 31 + .../supported-data-types/2-monetary.md | 34 + .../3-boolean-data-types.md | 59 + .../4-character-data-types.md | 91 + .../4.1-enumerated-types.md | 101 + .../5-binary-data-types.md | 54 + .../supported-data-types/6-date-time-types.md | 325 +++ .../supported-data-types/7-geometric.md | 118 ++ .../supported-data-types/8-network-address.md | 67 + .../9-bit-string-types.md | 51 + ...iew-of-system-catalogs-and-system-views.md | 119 ++ .../system-catalogs/GS_ASP.md | 43 + .../system-catalogs/GS_AUDITING_POLICY.md | 20 + .../GS_AUDITING_POLICY_ACCESS.md | 20 + .../GS_AUDITING_POLICY_FILTERS.md | 21 + .../GS_AUDITING_POLICY_PRIVILEGES.md | 20 + .../system-catalogs/GS_CLIENT_GLOBAL_KEYS.md | 21 + .../GS_CLIENT_GLOBAL_KEYS_ARGS.md | 20 + .../system-catalogs/GS_COLUMN_KEYS.md | 23 + .../system-catalogs/GS_COLUMN_KEYS_ARGS.md | 20 + .../system-catalogs/GS_DB_PRIVILEGE.md | 19 + .../system-catalogs/GS_ENCRYPTED_COLUMNS.md | 23 + .../system-catalogs/GS_ENCRYPTED_PROC.md | 20 + .../system-catalogs/GS_GLOBAL_CHAIN.md | 25 + .../system-catalogs/GS_GLOBAL_CONFIG.md | 17 + .../system-catalogs/GS_MASKING_POLICY.md | 20 + .../GS_MASKING_POLICY_ACTIONS.md | 21 + .../GS_MASKING_POLICY_FILTERS.md | 21 + .../system-catalogs/GS_MATVIEW.md | 21 + .../system-catalogs/GS_MATVIEW_DEPENDENCY.md | 20 + .../system-catalogs/GS_MODEL_WAREHOUSE.md | 38 + .../system-catalogs/GS_OPT_MODEL.md | 33 + .../system-catalogs/GS_PACKAGE.md | 24 + .../system-catalogs/GS_POLICY_LABEL.md | 24 + .../system-catalogs/GS_RECYCLEBIN.md | 35 + .../system-catalogs/GS_TXN_SNAPSHOT.md | 19 + .../system-catalogs/GS_UID.md | 17 + .../GS_WLM_EC_OPERATOR_INFO.md | 29 + .../GS_WLM_INSTANCE_HISTORY.md | 30 + .../system-catalogs/GS_WLM_OPERATOR_INFO.md | 37 + .../GS_WLM_PLAN_ENCODING_TABLE.md | 23 + .../GS_WLM_PLAN_OPERATOR_INFO.md | 32 + .../GS_WLM_SESSION_QUERY_INFO_ALL.md | 102 + .../GS_WLM_USER_RESOURCE_HISTORY.md | 33 + .../system-catalogs/PGXC_CLASS.md | 25 + .../system-catalogs/PGXC_GROUP.md | 24 + .../system-catalogs/PGXC_NODE.md | 32 + .../system-catalogs/PGXC_SLICE.md | 30 + .../system-catalogs/PG_AGGREGATE.md | 25 + .../system-catalogs/PG_AM.md | 47 + .../system-catalogs/PG_AMOP.md | 28 + .../system-catalogs/PG_AMPROC.md | 23 + .../PG_APP_WORKLOADGROUP_MAPPING.md | 18 + .../system-catalogs/PG_ATTRDEF.md | 21 + .../system-catalogs/PG_ATTRIBUTE.md | 39 + .../system-catalogs/PG_AUTHID.md | 44 + .../system-catalogs/PG_AUTH_HISTORY.md | 19 + .../system-catalogs/PG_AUTH_MEMBERS.md | 19 + .../system-catalogs/PG_CAST.md | 21 + .../system-catalogs/PG_CLASS.md | 78 + .../system-catalogs/PG_COLLATION.md | 22 + .../system-catalogs/PG_CONSTRAINT.md | 48 + .../system-catalogs/PG_CONVERSION.md | 23 + .../system-catalogs/PG_DATABASE.md | 31 + .../system-catalogs/PG_DB_ROLE_SETTING.md | 18 + .../system-catalogs/PG_DEFAULT_ACL.md | 20 + .../system-catalogs/PG_DEPEND.md | 32 + .../system-catalogs/PG_DESCRIPTION.md | 21 + .../system-catalogs/PG_DIRECTORY.md | 20 + .../system-catalogs/PG_ENUM.md | 23 + .../system-catalogs/PG_EXTENSION.md | 23 + .../PG_EXTENSION_DATA_SOURCE.md | 22 + .../PG_FOREIGN_DATA_WRAPPER.md | 22 + .../system-catalogs/PG_FOREIGN_SERVER.md | 23 + .../system-catalogs/PG_FOREIGN_TABLE.md | 19 + .../system-catalogs/PG_HASHBUCKET.md | 21 + .../system-catalogs/PG_INDEX.md | 35 + .../system-catalogs/PG_INHERITS.md | 18 + .../system-catalogs/PG_JOB.md | 36 + .../system-catalogs/PG_JOB_PROC.md | 19 + .../system-catalogs/PG_LANGUAGE.md | 24 + .../system-catalogs/PG_LARGEOBJECT.md | 22 + .../PG_LARGEOBJECT_METADATA.md | 18 + .../system-catalogs/PG_NAMESPACE.md | 22 + .../system-catalogs/PG_OBJECT.md | 30 + .../system-catalogs/PG_OPCLASS.md | 28 + .../system-catalogs/PG_OPERATOR.md | 30 + .../system-catalogs/PG_OPFAMILY.md | 24 + .../system-catalogs/PG_PARTITION.md | 45 + .../system-catalogs/PG_PLTEMPLATE.md | 23 + .../system-catalogs/PG_PROC.md | 55 + .../system-catalogs/PG_PUBLICATION.md | 21 + .../system-catalogs/PG_PUBLICATION_REL.md | 17 + .../system-catalogs/PG_RANGE.md | 23 + .../system-catalogs/PG_REPLICATION_ORIGIN.md | 17 + .../system-catalogs/PG_RESOURCE_POOL.md | 31 + .../system-catalogs/PG_REWRITE.md | 24 + .../system-catalogs/PG_RLSPOLICY.md | 22 + .../system-catalogs/PG_SECLABEL.md | 22 + .../system-catalogs/PG_SHDEPEND.md | 45 + .../system-catalogs/PG_SHDESCRIPTION.md | 22 + .../system-catalogs/PG_SHSECLABEL.md | 25 + .../system-catalogs/PG_STATISTIC.md | 30 + .../system-catalogs/PG_STATISTIC_EXT.md | 30 + .../system-catalogs/PG_SUBSCRIPTION.md | 24 + .../system-catalogs/PG_SYNONYM.md | 21 + .../system-catalogs/PG_TABLESPACE.md | 22 + .../system-catalogs/PG_TRIGGER.md | 32 + .../system-catalogs/PG_TS_CONFIG.md | 23 + .../system-catalogs/PG_TS_CONFIG_MAP.md | 19 + .../system-catalogs/PG_TS_DICT.md | 23 + .../system-catalogs/PG_TS_PARSER.md | 23 + .../system-catalogs/PG_TS_TEMPLATE.md | 20 + .../system-catalogs/PG_TYPE.md | 46 + .../system-catalogs/PG_USER_MAPPING.md | 21 + .../system-catalogs/PG_USER_STATUS.md | 23 + .../system-catalogs/PG_WORKLOAD_GROUP.md | 19 + .../system-catalogs/PLAN_TABLE_DATA.md | 32 + .../system-catalogs/STATEMENT_HISTORY.md | 73 + .../system-views/DV_SESSIONS.md | 19 + .../system-views/DV_SESSION_LONGOPS.md | 19 + .../system-views/GET_GLOBAL_PREPARED_XACTS.md | 10 + .../GS_ASYNC_SUBMIT_SESSIONS_STATUS.md | 25 + .../system-views/GS_AUDITING.md | 22 + .../system-views/GS_AUDITING_ACCESS.md | 22 + .../system-views/GS_AUDITING_PRIVILEGE.md | 22 + .../system-views/GS_CLUSTER_RESOURCE_INFO.md | 22 + .../system-views/GS_DB_PRIVILEGES.md | 18 + .../system-views/GS_FILE_STAT.md | 28 + .../system-views/GS_GSC_MEMORY_DETAIL.md | 19 + .../system-views/GS_INSTANCE_TIME.md | 29 + .../system-views/GS_LABELS.md | 19 + .../system-views/GS_LSC_MEMORY_DETAIL.md | 24 + .../system-views/GS_MASKING.md | 19 + .../system-views/GS_MATVIEWS.md | 21 + .../system-views/GS_OS_RUN_INFO.md | 20 + .../system-views/GS_REDO_STAT.md | 22 + .../system-views/GS_SESSION_CPU_STATISTICS.md | 25 + .../system-views/GS_SESSION_MEMORY.md | 19 + .../system-views/GS_SESSION_MEMORY_CONTEXT.md | 25 + .../system-views/GS_SESSION_MEMORY_DETAIL.md | 27 + .../GS_SESSION_MEMORY_STATISTICS.md | 25 + .../system-views/GS_SESSION_STAT.md | 20 + .../system-views/GS_SESSION_TIME.md | 19 + .../system-views/GS_SQL_COUNT.md | 45 + .../system-views/GS_STAT_SESSION_CU.md | 18 + .../system-views/GS_THREAD_MEMORY_CONTEXT.md | 26 + .../system-views/GS_TOTAL_MEMORY_DETAIL.md | 18 + .../system-views/GS_WLM_CGROUP_INFO.md | 24 + .../GS_WLM_EC_OPERATOR_STATISTICS.md | 25 + .../system-views/GS_WLM_OPERATOR_HISTORY.md | 12 + .../GS_WLM_OPERATOR_STATISTICS.md | 38 + .../GS_WLM_PLAN_OPERATOR_HISTORY.md | 35 + .../GS_WLM_REBUILD_USER_RESOURCE_POOL.md | 16 + .../system-views/GS_WLM_RESOURCE_POOL.md | 25 + .../system-views/GS_WLM_SESSION_HISTORY.md | 83 + .../system-views/GS_WLM_SESSION_INFO.md | 12 + .../system-views/GS_WLM_SESSION_INFO_ALL.md | 44 + .../system-views/GS_WLM_SESSION_STATISTICS.md | 64 + .../system-views/GS_WLM_USER_INFO.md | 25 + .../system-views/GS_WRITE_TERM_LOG.md | 10 + .../system-views/MPP_TABLES.md | 21 + .../system-views/PGXC_PREPARED_XACTS.md | 16 + .../system-views/PG_AVAILABLE_EXTENSIONS.md | 19 + .../PG_AVAILABLE_EXTENSION_VERSIONS.md | 23 + .../system-views/PG_COMM_DELAY.md | 22 + .../system-views/PG_COMM_RECV_STREAM.md | 32 + .../system-views/PG_COMM_SEND_STREAM.md | 32 + .../system-views/PG_COMM_STATUS.md | 28 + .../system-views/PG_CONTROL_GROUP_CONFIG.md | 16 + .../system-views/PG_CURSORS.md | 21 + .../system-views/PG_EXT_STATS.md | 28 + .../system-views/PG_GET_INVALID_BACKENDS.md | 20 + .../PG_GET_SENDERS_CATCHUP_TIME.md | 23 + .../system-views/PG_GROUP.md | 18 + .../system-views/PG_GTT_ATTACHED_PIDS.md | 19 + .../system-views/PG_GTT_RELSTATS.md | 23 + .../system-views/PG_GTT_STATS.md | 29 + .../system-views/PG_INDEXES.md | 20 + .../system-views/PG_LOCKS.md | 34 + .../system-views/PG_NODE_ENV.md | 22 + .../system-views/PG_OS_THREADS.md | 20 + .../system-views/PG_PREPARED_STATEMENTS.md | 20 + .../system-views/PG_PREPARED_XACTS.md | 20 + .../system-views/PG_PUBLICATION_TABLES.md | 18 + .../PG_REPLICATION_ORIGIN_STATUS.md | 19 + .../system-views/PG_REPLICATION_SLOTS.md | 25 + .../system-views/PG_RLSPOLICIES.md | 22 + .../system-views/PG_ROLES.md | 42 + .../system-views/PG_RULES.md | 19 + .../system-views/PG_RUNNING_XACTS.md | 25 + .../system-views/PG_SECLABELS.md | 23 + .../system-views/PG_SESSION_IOSTAT.md | 27 + .../system-views/PG_SESSION_WLMSTAT.md | 39 + .../system-views/PG_SETTINGS.md | 31 + .../system-views/PG_SHADOW.md | 31 + .../system-views/PG_STATIO_ALL_INDEXES.md | 22 + .../system-views/PG_STATIO_ALL_SEQUENCES.md | 20 + .../system-views/PG_STATIO_ALL_TABLES.md | 26 + .../system-views/PG_STATIO_SYS_INDEXES.md | 22 + .../system-views/PG_STATIO_SYS_SEQUENCES.md | 20 + .../system-views/PG_STATIO_SYS_TABLES.md | 26 + .../system-views/PG_STATIO_USER_INDEXES.md | 22 + .../system-views/PG_STATIO_USER_SEQUENCES.md | 20 + .../system-views/PG_STATIO_USER_TABLES.md | 26 + .../system-views/PG_STATS.md | 30 + .../system-views/PG_STAT_ACTIVITY.md | 38 + .../system-views/PG_STAT_ACTIVITY_NG.md | 36 + .../system-views/PG_STAT_ALL_INDEXES.md | 25 + .../system-views/PG_STAT_ALL_TABLES.md | 37 + .../system-views/PG_STAT_BAD_BLOCK.md | 24 + .../system-views/PG_STAT_BGWRITER.md | 26 + .../system-views/PG_STAT_DATABASE.md | 34 + .../PG_STAT_DATABASE_CONFLICTS.md | 22 + .../system-views/PG_STAT_REPLICATION.md | 30 + .../system-views/PG_STAT_SUBSCRIPTION.md | 23 + .../system-views/PG_STAT_SYS_INDEXES.md | 23 + .../system-views/PG_STAT_SYS_TABLES.md | 37 + .../system-views/PG_STAT_USER_FUNCTIONS.md | 21 + .../system-views/PG_STAT_USER_INDEXES.md | 23 + .../system-views/PG_STAT_USER_TABLES.md | 37 + .../system-views/PG_STAT_XACT_ALL_TABLES.md | 26 + .../system-views/PG_STAT_XACT_SYS_TABLES.md | 26 + .../PG_STAT_XACT_USER_FUNCTIONS.md | 21 + .../system-views/PG_STAT_XACT_USER_TABLES.md | 26 + .../system-views/PG_TABLES.md | 25 + .../system-views/PG_TDE_INFO.md | 18 + .../system-views/PG_THREAD_WAIT_STATUS.md | 290 +++ .../system-views/PG_TIMEZONE_ABBREVS.md | 18 + .../system-views/PG_TIMEZONE_NAMES.md | 19 + .../system-views/PG_TOTAL_MEMORY_DETAIL.md | 18 + .../PG_TOTAL_USER_RESOURCE_INFO.md | 32 + .../PG_TOTAL_USER_RESOURCE_INFO_OID.md | 32 + .../system-views/PG_USER.md | 31 + .../system-views/PG_USER_MAPPINGS.md | 23 + .../system-views/PG_VARIABLE_INFO.md | 26 + .../system-views/PG_VIEWS.md | 19 + .../system-views/PG_WLM_STATISTICS.md | 24 + .../system-views/PLAN_TABLE.md | 31 + .../reference-guide/tool-reference/FAQ.md | 133 ++ .../tool-reference/client-tool/1-gsql.md | 941 ++++++++ .../tool-reference/client-tool/client-tool.md | 10 + .../functions-of-mogdb-executable-scripts.md | 52 + .../server-tools/0-gs_cgroup.md | 444 ++++ .../tool-reference/server-tools/1-gs_check.md | 1162 ++++++++++ .../tool-reference/server-tools/10-gs_ssh.md | 76 + .../server-tools/2-gs_checkos.md | 223 ++ .../server-tools/3-gs_checkperf.md | 296 +++ .../server-tools/3.1-gs_clean.md | 100 + .../server-tools/4-gs_collector.md | 227 ++ .../tool-reference/server-tools/5-gs_dump.md | 563 +++++ .../server-tools/6-gs_dumpall.md | 285 +++ .../tool-reference/server-tools/7-gs_guc.md | 394 ++++ .../server-tools/7.1-gs_encrypt.md | 136 ++ .../tool-reference/server-tools/8-gs_om.md | 398 ++++ .../server-tools/9-gs_restore.md | 399 ++++ .../server-tools/gs_gucquery.md | 51 + .../tool-reference/server-tools/gs_watch.md | 52 + ...ogs-and-views-supported-by-gs_collector.md | 375 ++++ .../tool-reference/tool-overview.md | 74 + .../1-gaussdb.md | 177 ++ .../10-gs_tar.md | 49 + .../11-gs_uninstall.md | 80 + .../12-gs_upgradectl.md | 250 +++ .../13-gs_expansion.md | 182 ++ .../14-gs_dropnode.md | 126 ++ .../15-gs_probackup.md | 820 +++++++ .../16-gstrace.md | 146 ++ .../17-kdb5_util.md | 16 + .../18-kadmin-local.md | 16 + .../19-kinit.md | 16 + .../2-gs_backup.md | 151 ++ .../20-klist.md | 16 + .../21-krb5kdc.md | 16 + .../22-kdestroy.md | 16 + .../23-pg_config.md | 118 ++ .../24-pg_controldata.md | 50 + .../24.1-pg_recvlogical.md | 157 ++ .../25-pg_resetxlog.md | 72 + .../26-pg_archivecleanup.md | 58 + .../27-pssh.md | 68 + .../28-pscp.md | 72 + .../29-transfer.py.md | 60 + .../3-gs_basebackup.md | 164 ++ .../4-gs_ctl.md | 119 ++ .../5-gs_initdb.md | 120 ++ .../6-gs_install.md | 127 ++ .../7-gs_postuninstall.md | 119 ++ .../8-gs_preinstall.md | 307 +++ .../9-gs_sshexkey.md | 135 ++ .../gs_install_plugin.md | 218 ++ .../gs_install_plugin_local.md | 212 ++ .../unified-database-management-tool.md | 1110 ++++++++++ .../1-client-access-authentication.md | 807 +++++++ .../2-managing-users-and-their-permissions.md | 1063 ++++++++++ .../security/3-configuring-database-audit.md | 367 ++++ .../4-setting-encrypted-equality-query.md | 333 +++ .../security/5-setting-a-ledger-database.md | 406 ++++ .../security/6-transparent-data-encryption.md | 88 + .../zh/docs-mogdb/v3.1/source-code-parsing.md | 88 + product/zh/docs-mogdb/v3.1/toc.md | 1663 +++++++++++++++ product/zh/docs-mogdb/v3.1/toc_about.md | 22 + product/zh/docs-mogdb/v3.1/toc_ai-features.md | 90 + .../v3.1/toc_characteristic_description.md | 113 + .../toc_common-faults-and-identification.md | 43 + .../v3.1/toc_communication-matrix.md | 5 + .../docs-mogdb/v3.1/toc_datatypes-and-sql.md | 286 +++ product/zh/docs-mogdb/v3.1/toc_dev.md | 208 ++ product/zh/docs-mogdb/v3.1/toc_error.md | 89 + .../v3.1/toc_extension-referecne.md | 20 + product/zh/docs-mogdb/v3.1/toc_faqs.md | 12 + product/zh/docs-mogdb/v3.1/toc_glossary.md | 5 + product/zh/docs-mogdb/v3.1/toc_install.md | 21 + product/zh/docs-mogdb/v3.1/toc_manage.md | 78 + .../v3.1/toc_parameters-and-tools.md | 389 ++++ product/zh/docs-mogdb/v3.1/toc_performance.md | 26 + product/zh/docs-mogdb/v3.1/toc_quickstart.md | 29 + product/zh/docs-mogdb/v3.1/toc_secure.md | 12 + .../v3.1/toc_system-catalogs-and-functions.md | 292 +++ src/utils/version_config.js | 5 + 1478 files changed, 200644 insertions(+) create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/1-AI-features-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-best-practices.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-environment-deployment.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-faqs.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-user-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-1-x-tuner-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-2-preparations.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-3-examples.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-4-obtaining-help-information.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-5-command-reference.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-6-Troubleshooting.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-1-single-query-index-recommendation.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-2-virtual-index.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-3-workload-level-index-recommendation.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-1-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-2-environment-deployment.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-3-usage-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-4-obtaining-help-information.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-5-command-reference.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-6-troubleshooting.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-1-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-2-environment-deployment.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-3-usage-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-4-obtaining-help-information.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-5-command-reference.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-6-troubleshooting.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-1-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-2-usage-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-3-obtaining-help-information.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-4-command-reference.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-5-troubleshooting.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai4db-autonomous-database-o&m.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/components-that-support-dbmind.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-command-reference.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-environment-deployment.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-obtaining-help-information.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-troubleshooting.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-usage-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/1-service.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/2-component.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/3-set.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/dbmind-mode.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/db4ai/db4ai.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/db4ai-snapshots-for-data-version-management.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/full-process-ai.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/plpython-fenced-mode.md create mode 100644 product/zh/docs-mogdb/v3.1/AI-features/db4ai/native-db4ai-engine.md create mode 100644 product/zh/docs-mogdb/v3.1/_index.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/MogDB-compared-to-openGauss.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.0.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.1.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.2.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/release-note.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/1-enhanced-opengauss-kernel.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/2-docker-based-mogdb.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/5-wal2json-extention-for-mogdb&opengauss.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/DBMS-RANDOM.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/compat-tools.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mog_filedump.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mog_xlogdump.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mogdb-monitor.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/terms-of-use.md create mode 100644 product/zh/docs-mogdb/v3.1/about-mogdb/usage-limitations.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/br/1-1-br.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/br/1-2-br.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/br/1-3-br.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/br/1-4-br.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/column-store-tables-management.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/1-using-gs_dump-and-gs_dumpall-to-export-data-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/2-exporting-a-single-database.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/3-exporting-all-databases.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/4-data-export-by-a-user-without-required-permissions.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/1-import-modes.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/10-managing-concurrent-write-operations.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/2-running-the-INSERT-statement-to-insert-data.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/3-running-the-COPY-FROM-STDIN-statement-to-import-data.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/4-using-a-gsql-meta-command-to-import-data.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/5-using-gs_restore-to-import-data.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/6-updating-data-in-a-table.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/7-deep-copy.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/8-ANALYZE-table.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/9-doing-VACUUM-to-a-table.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/localization/character-set-support.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/localization/collation-support.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/localization/locale-support.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/1-mot-introduction.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/2-mot-features-and-benefits.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/3-mot-key-technologies.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/4-mot-usage-scenarios.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/5-mot-performance-benchmarks.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/1-using-mot-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/2-mot-preparation.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/3-mot-deployment.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/4-mot-usage.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/5-mot-administration.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/6-mot-sample-tpcc-benchmark.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-1.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-2.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-3.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-4.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-5.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-6.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-7.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-8.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-9.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/4-appendix/1-references.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/4-appendix/2-glossary.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/primary-and-standby-management.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/0-starting-and-stopping-mogdb.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/1-routine-maintenance-check-items.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/10-data-security-maintenance-suggestions.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/11-log-reference.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/2-checking-os-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/3-checking-mogdb-health-status.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/4-checking-database-performance.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/5-checking-and-deleting-logs.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/6-checking-time-consistency.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/7-checking-the-number-of-application-connections.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/8-routinely-maintaining-tables.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/9-routinely-recreating-an-index.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/slow-sql-diagnosis.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/using-the-gsql-client-for-connection.md create mode 100644 product/zh/docs-mogdb/v3.1/administrator-guide/upgrade-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai-in-db/predictor-ai-query-time-forecasting.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/1-database-metric-collection-forecast-and-exception-detection.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/2-root-cause-analysis-for-slow-sql-statements.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/3-index-recommendation.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/4-parameter-tuning-and-diagnosis.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/5-slow-sql-statement-discovery.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/db4ai-database-driven-ai.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/1-standard-sql.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/2-standard-development-interfaces.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/3-postgresql-api-compatibility.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/4-pl-java.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/MogDB-MySQL-compatibility.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/MogDB-Oracle-compatibility.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/characteristic-description-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/1-access-control-model.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/10-row-level-access-control.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/11-password-strength-verification.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/12-equality-query-in-a-fully-encrypted-database.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/13-ledger-database-mechanism.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/14-transparent-data-encryption.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/2-separation-of-control-and-access-permissions.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/3-database-encryption-authentication.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/4-data-encryption-and-storage.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/5-database-audit.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/6-network-communication-security.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/7-resource-label.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/8-unified-audit.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/database-security/9-dynamic-data-anonymization.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/1-support-for-functions-and-stored-procedures.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/10-autonomous-transaction.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/11-global-temporary-table.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/12-pseudocolumn-rownum.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/13-stored-procedure-debugging.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/14-jdbc-client-load-balancing-and-readwrite-isolation.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/15-in-place-update-storage-engine.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/16-publication-subscription.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/17-foreign-key-lock-enhancement.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/18-data-compression-in-oltp-scenarios.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/19-transaction-async-submit.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/2-sql-hints.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/20-copy-import-optimization.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/21-dynamic-partition-pruning.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/22-sql-running-status-observation.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/23-index-creation-parallel-control.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/24-brin-index.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/25-bloom-index.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/26-backend-compression.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/3-full-text-indexing.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/4-copy-interface-for-error-tolerance.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/5-partitioning.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/6-support-for-advanced-analysis-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/7-materialized-view.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/8-hyperloglog.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/9-creating-an-index-online.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/1-primary-standby.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/10-adding-or-deleting-a-standby-server.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/11-delaying-entering-the-maximum-availability-mode.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/12-parallel-logical-decoding.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/13-dcf.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/14-cm.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/15-global-syscache.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/16-using-a-standby-node-to-build-a-standby-node.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/2-logical-replication.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/3-online-node-replacement.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/4-logical-backup.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/5-physical-backup.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/6-automatic-job-retry-upon-failure.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/7-ultimate-rto.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/8-cascaded-standby-server.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/9-delayed-replay.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/1-cbo-optimizer.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/10-xlog-no-lock-flush.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/11-parallel-page-based-redo-for-ustore.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/12-row-store-execution-to-vectorized-execution.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/2-llvm.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/3-vectorized-engine.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/4-hybrid-row-column-store.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/5-adaptive-compression.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/6-sql-by-pass.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/7-kunpeng-numa-architecture-optimization.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/8-high-concurrency-of-thread-pools.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/9-smp-for-parallel-execution.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/1-gray-upgrade.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/2-workload-diagnosis-report.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/3-slow-sql-diagnosis.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/4-session-performance-diagnosis.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/5-system-kpi-aided-diagnosis.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/fault-diagnosis.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/middleware/deploying-a-distributed-database-using-kubernetes.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/middleware/distributed-database-capability.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/tool-chain/mogdb-client-tool-datastudio.md create mode 100644 product/zh/docs-mogdb/v3.1/characteristic-description/tool-chain/mysql-to-mogdb-migration-tool-chameleon.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/1-core-dump-occurs-due-to-full-disk-space.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/2-core-dump-occurs-due-to-incorrect-settings-of-guc-parameter-log-directory.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/3-core-dump-occurs-when-removeipc-is-enabled.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/4-core-dump-occurs-after-installation-on-x86.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/10-disk-space-usage-reaches-the-threshold.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/11-slow-response-to-a-query-statement.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/12-analyzing-the-status-of-a-query-statement.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/13-forcibly-terminating-a-session.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/14-analyzing-whether-a-query-statement-is-blocked.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/15-low-query-efficiency.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/16-lock-wait-timeout-is-displayed.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/17-table-size-does-not-change.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/18-an-error-is-reported-when-the-table-partition-is-modified.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/19-different-data-is-displayed.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/2-when-the-tpcc-is-running.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/20-when-a-user-specifies-only-an-index-name.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/21-reindexing-fails.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/22-an-error-occurs-during-integer-conversion.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/23-too-many-clients-already.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/24-b-tree-index-faults.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/3-standby-node-in-the-need-repair-state.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/4-insufficient-memory.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/5-service-startup-failure.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/6-error-no-space-left-on-device-is-displayed.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/7-after-you-run-the-du-command.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/8-file-is-damaged-in-the-xfs-file-system.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/9-primary-node-is-hung-in-demoting.md create mode 100644 product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-methods.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/1-1-stored-procedure.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/1-introduction-to-autonomous-transaction.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/2-function-supporting-autonomous-transaction.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/3-stored-procedure-supporting-autonomous-transaction.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/4-restrictions.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/anonymous-block-supporting-autonomous-transaction.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/1-development-specifications.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/1-development-based-on-jdbc-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/10-example-common-operations.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/11-example-retrying-sql-queries-for-applications.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/12-example-importing-and-exporting-data-through-local-files.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/13-example-2-migrating-data-from-a-my-database-to-mogdb.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/14-example-logic-replication-code.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/14.1-example-parameters-for-connecting-to-the-database-in-different-scenarios.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/1-java-sql-Connection.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/10-javax-sql-DataSource.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/11-javax-sql-PooledConnection.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/12-javax-naming-Context.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/13-javax-naming-spi-InitialContextFactory.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/14-CopyManager.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/2-java-sql-CallableStatement.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/3-java-sql-DatabaseMetaData.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/4-java-sql-Driver.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/5-java-sql-PreparedStatement.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/6-java-sql-ResultSet.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/7-java-sql-ResultSetMetaData.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/8-java-sql-Statement.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/9-javax-sql-ConnectionPoolDataSource.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/2-jdbc-package-driver-class-and-environment-class.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/3-development-process.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/4-loading-the-driver.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/5-connecting-to-a-database.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/6-connecting-to-a-database-using-ssl.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/7-running-sql-statements.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/8-processing-data-in-a-result-set.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/8.1-log-management.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/9-closing-a-connection.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/1-development-based-on-odbc-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/2-odbc-packages-dependent-libraries-and-header-files.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/3-configuring-a-data-source-in-the-linux-os.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/4-development-process.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/5-example-common-functions-and-batch-binding.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/5.1-typical-application-scenarios-and-configurations.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-0-odbc-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-1-SQLAllocEnv.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-10-SQLExecDirect.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-11-SQLExecute.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-12-SQLFetch.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-13-SQLFreeStmt.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-14-SQLFreeConnect.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-15-SQLFreeHandle.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-16-SQLFreeEnv.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-17-SQLPrepare.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-18-SQLGetData.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-19-SQLGetDiagRec.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-2-SQLAllocConnect.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-20-SQLSetConnectAttr.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-21-SQLSetEnvAttr.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-22-SQLSetStmtAttr.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-23-Examples.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-3-SQLAllocHandle.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-4-SQLAllocStmt.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-5-SQLBindCol.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-6-SQLBindParameter.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-7-SQLColAttribute.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-8-SQLConnect.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-9-SQLDisconnect.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/1-database-connection-control-functions-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/10-PQstatus.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/2-PQconnectdbParams.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/3-PQconnectdb.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/4-PQconninfoParse.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/5-PQconnectStart.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/6-PQerrorMessage.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/7-PQsetdbLogin.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/8-PQfinish.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/9-PQreset.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/1-PQclear.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/10-PQntuples.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/11-PQprepare.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/12-PQresultStatus.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/2-PQexec.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/3-PQexecParams.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/4-PQexecParamsBatch.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/5-PQexecPrepared.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/6-PQexecPreparedBatch.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/7-PQfname.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/8-PQgetvalue.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/9-PQnfields.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/1-functions-for-asynchronous-command-processing-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/2-PQsendQuery.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/3-PQsendQueryParams.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/4-PQsendPrepare.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/5-PQsendQueryPrepared.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/6-PQflush.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/1-PQgetCancel.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/2-PQfreeCancel.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/3-PQcancel.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/dependent-header-files-of-libpq.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/development-process.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/libpq-example.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/link-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/1-psycopg-based-development.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/1-psycopg2-connect.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/10-connection-close.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/2-connection-cursor.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/3-cursor-execute-query-vars-list.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/4-curosr-executemany-query-vars-list.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/5-connection-commit.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/6-connection-rollback.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/7-cursor-fetchone.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/8-cursor-fetchall.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/9-cursor-close.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/2-psycopg-package.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/3.1-development-process.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/4-loading-a-driver.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/5.1-connecting-to-a-database.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/6-executing-sql-statements.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/7-processing-the-result-set.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/8-closing-the-connection.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/9-connecting-to-the-database-using-ssl.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/dev/5-commissioning.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/1-oracle_fdw.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/2-mysql_fdw.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/3-postgres_fdw.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/dblink.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/fdw-introduction.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/file_fdw.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/logical-decoding/1-logical-decoding.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/logical-decoding/2-logical-decoding-by-sql-function-interfaces.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/architecture.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/configuration-settings.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/conflicts.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/monitoring.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/publication-subscription.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/publications.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/quick-setup.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/restrictions.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/security.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/subscriptions.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/1-materialized-view-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/1-full-materialized-view-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/2-full-materialized-view-usage.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/3-full-materialized-view-support-and-constraints.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/1-incremental-materialized-view-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/2-incremental-materialized-view-usage.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/3-incremental-materialized-view-support-and-constraints.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/benefits-of-partition-pruning.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/dynamic-partition-pruning.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/how-to-identify-whether-partition-pruning-has-been-used.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/information-that-can-be-used-for-partition-pruning.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/static-partition-pruning.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-hash-partitioning.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-list-partitioning.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-range-partitioning.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-1-plpgsql-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-10-other-statements.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-11-cursors.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-12-retry-management.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-13-debugging.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-14-package.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-2-data-types.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-3-data-type-conversion.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-4-arrays-and-records.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-5-declare-syntax.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-6-basic-statements.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-7-dynamic-statements.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-8-control-statements.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-9-transaction-management.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/advanced-packages/basic-interfaces/PKG_SERVICE.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/scheduled-jobs/pkg-service.md create mode 100644 product/zh/docs-mogdb/v3.1/developer-guide/user-defined-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/faqs/application-development-faqs.md create mode 100644 product/zh/docs-mogdb/v3.1/faqs/deployment-and-maintenance-faqs.md create mode 100644 product/zh/docs-mogdb/v3.1/faqs/high-availability-faqs.md create mode 100644 product/zh/docs-mogdb/v3.1/faqs/migration-faqs.md create mode 100644 product/zh/docs-mogdb/v3.1/faqs/product-faqs.md create mode 100644 product/zh/docs-mogdb/v3.1/faqs/upgrade-faqs.md create mode 100644 product/zh/docs-mogdb/v3.1/glossary.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/docker-installation/docker-installation.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/installation-preparation/environment-requirement.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/installation-preparation/os-configuration.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/manual-installation.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/om-installation/installation-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/om-installation/obtaining-installation-package.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/om-installation/simple-installation.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/om-installation/standard-installation.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/om-installation/uninstallation.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/om-installation/verifying-installation.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/ptk-based-installation.md create mode 100644 product/zh/docs-mogdb/v3.1/installation-guide/recommended-parameter-settings.md create mode 100644 product/zh/docs-mogdb/v3.1/mogeaver/mogeaver-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/mogeaver/mogeaver-release-notes.md create mode 100644 product/zh/docs-mogdb/v3.1/overview.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/1-system/1-optimizing-os-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/1-system/2-optimizing-database-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/1-system/3-configuring-llvm.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/1-system/4-configuring-smp.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/1-query-execution-process.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/2-introduction-to-the-sql-execution-plan.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/3-tuning-process.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/4-updating-statistics.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/5-reviewing-and-modifying-a-table-definition.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/6-typical-sql-optimization-methods.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/7-experience-in-rewriting-sql-statements.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/8-resetting-key-parameters-during-sql-tuning.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/2-sql/9-hint-based-tuning.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/3-wdr/wdr-report.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/3-wdr/wdr-snapshot-schema.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/TPCC-performance-tuning-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/performance-tuning/tuning-with-vector-engine.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/container-based-installation.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/installation-on-a-single-node.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-cli-to-access-mogdb/gsql.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-cli-to-access-mogdb/pgcli.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-gui-tools-to-access-mogdb/datastudio.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-gui-tools-to-access-mogdb/dbeaver.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-gui-tools-to-access-mogdb/mogeaver-usage.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-middleware-to-access-mogdb/weblogic-configures-mogdb-data-source-reference.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-middleware-to-access-mogdb/websphere-configures-mogdb-data-source-reference.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-programming-language-to-access-mogdb/adonet.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-programming-language-to-access-mogdb/c-cpp.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-programming-language-to-access-mogdb/go.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-programming-language-to-access-mogdb/java.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-programming-language-to-access-mogdb/nodejs.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-programming-language-to-access-mogdb/python.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-access/use-programming-language-to-access-mogdb/rust.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogdb-playground.md create mode 100644 product/zh/docs-mogdb/v3.1/quick-start/mogila.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/1-GAUSS-00001-GAUSS-00100.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/10-GAUSS-00901-GAUSS-01000.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/11-GAUSS-01001-GAUSS-01100.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/12-GAUSS-01101-GAUSS-01200.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/13-GAUSS-01201-GAUSS-01300.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/14-GAUSS-01301-GAUSS-01400.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/15-GAUSS-01401-GAUSS-01500.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/16-GAUSS-01501-GAUSS-01600.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/17-GAUSS-01601-GAUSS-01700.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/18-GAUSS-01701-GAUSS-01800.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/19-GAUSS-01801-GAUSS-01900.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/2-GAUSS-00101-GAUSS-00200.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/20-GAUSS-01901-GAUSS-02000.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/21-GAUSS-02001-GAUSS-02100.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/22-GAUSS-02101-GAUSS-02200.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/23-GAUSS-02201-GAUSS-02300.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/24-GAUSS-02301-GAUSS-02400.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/25-GAUSS-02401-GAUSS-02500.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/26-GAUSS-02501-GAUSS-02600.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/27-GAUSS-02601-GAUSS-02700.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/28-GAUSS-02701-GAUSS-02800.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/29-GAUSS-02801-GAUSS-02900.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/3-GAUSS-00201-GAUSS-00300.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/30-GAUSS-02901-GAUSS-03000.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/31-GAUSS-03001-GAUSS-03100.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/32-GAUSS-03101-GAUSS-03200.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/33-GAUSS-03201-GAUSS-03300.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/34-GAUSS-03301-GAUSS-03400.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/35-GAUSS-03401-GAUSS-03500.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/36-GAUSS-03501-GAUSS-03600.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/37-GAUSS-03601-GAUSS-03700.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/38-GAUSS-03701-GAUSS-03800.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/39-GAUSS-03801-GAUSS-03900.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/4-GAUSS-00301-GAUSS-00400.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/40-GAUSS-03901-GAUSS-04000.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/41-GAUSS-04001-GAUSS-04100.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/42-GAUSS-04101-GAUSS-04200.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/43-GAUSS-04201-GAUSS-04300.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/44-GAUSS-04301-GAUSS-04400.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/45-GAUSS-04401-GAUSS-04500.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/46-GAUSS-04501-GAUSS-04600.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/47-GAUSS-04601-GAUSS-04700.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/48-GAUSS-04701-GAUSS-04800.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/49-GAUSS-04801-GAUSS-04900.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/5-GAUSS-00401-GAUSS-00500.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/50-GAUSS-04901-GAUSS-05000.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/51-GAUSS-05001-GAUSS-05100.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/52-GAUSS-05101-GAUSS-05200.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/53-GAUSS-05201-GAUSS-05300.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/54-GAUSS-05301-GAUSS-05400.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/55-GAUSS-05401-GAUSS-05500.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/56-GAUSS-05501-GAUSS-05600.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/57-GAUSS-05601-GAUSS-05700.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/58-GAUSS-05701-GAUSS-05800.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/59-GAUSS-05801-GAUSS-05900.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/6-GAUSS-00501-GAUSS-00600.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/60-GAUSS-05901-GAUSS-06000.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/61-GAUSS-06001-GAUSS-06100.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/62-GAUSS-06101-GAUSS-06200.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/63-GAUSS-06201-GAUSS-06300.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/64-GAUSS-06301-GAUSS-06400.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/65-GAUSS-06401-GAUSS-06500.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/66-GAUSS-06501-GAUSS-06600.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/67-GAUSS-06601-GAUSS-06700.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/68-GAUSS-06701-GAUSS-06800.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/69-GAUSS-06801-GAUSS-06900.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/7-GAUSS-00601-GAUSS-00700.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/70-GAUSS-06901-GAUSS-07000.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/71-GAUSS-07001-GAUSS-07100.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/72-GAUSS-07101-GAUSS-07200.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/73-GAUSS-07201-GAUSS-07300.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/74-GAUSS-07301-GAUSS-07400.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/75-GAUSS-07401-GAUSS-07480.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/76-GAUSS-50000-GAUSS-50999.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/77-GAUSS-51000-GAUSS-51999.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/78-GAUSS-52000-GAUSS-52999.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/79-GAUSS-53000-GAUSS-53699.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/8-GAUSS-00701-GAUSS-00800.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/9-GAUSS-00801-GAUSS-00900.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/description-of-sql-error-codes.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-code-reference/third-party-library-error-codes.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/error-log-reference/kernel-error-message.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/1-logical-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/10-geometric-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/11-network-address-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/12-text-search-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/13-json-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/13.1-hll-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/14-sequence-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/15-array-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/16-range-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/17-aggregate-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/18-window-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/19-security-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/2-comparison-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/20-encrypted-equality-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/20.1-ledger-database-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/21-set-returning-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/22-conditional-expressions-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/23-system-information-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/1-configuration-settings-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/10-undo-system-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/2-universal-file-access-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/3-server-signal-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/4-backup-and-restoration-control-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/5-snapshot-synchronization-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/6-database-object-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/7-advisory-lock-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/8-logical-replication-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/9-other-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/24-system-management-functions/9.1-segment-page-storage-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/25-statistics-information-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/26-trigger-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/27-global-temporary-table-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/27.1-hash-function.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/27.2-prompt-message-function.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/28-ai-feature-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/28.1-fault-injection-system-function.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/29-other-system-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/29.1-dynamic-data-masking-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/3-character-processing-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/30-internal-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/31-obsolete-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/32-global-syscache-feature-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/33-data-damage-detection-and-repair-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/4-binary-string-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/5-bit-string-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/6-mode-matching-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/7-mathematical-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/8-date-and-time-processing-functions-and-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/functions-and-operators/9-type-conversion-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/1-guc-parameter-usage.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/10-error-reporting-and-logging/1-logging-destination.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/10-error-reporting-and-logging/2-logging-time.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/10-error-reporting-and-logging/3-logging-content.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/10-error-reporting-and-logging/4-using-csv-log-output.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/11-alarm-detection.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/12-statistics-during-the-database-running/1-query-and-index-statistics-collector.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/12-statistics-during-the-database-running/2-performance-statistics.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/13-load-management.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/14-automatic-vacuuming.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/15-default-settings-of-client-connection/1-statement-behavior.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/15-default-settings-of-client-connection/2-zone-and-formatting.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/15-default-settings-of-client-connection/3-other-default-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/16-lock-management.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/17-version-and-platform-compatibility/1-compatibility-with-earlier-versions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/17-version-and-platform-compatibility/2-platform-and-client-compatibility.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/18-fault-tolerance.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/19-connection-pool-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/2-file-location.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/20-MogDB-transaction.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/21-developer-options.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/22-auditing/1-audit-switch.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/22-auditing/2-user-and-permission-audit.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/22-auditing/3-operation-audit.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/23-upgrade-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/24-miscellaneous-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/25-wait-events.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/26-query.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/27-system-performance-snapshot.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/27.1-security-configuration.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/29-global-temporary-table.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/29.1-HyperLogLog.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/3-connection-and-authentication/1-connection-settings.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/3-connection-and-authentication/2-security-and-authentication.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/3-connection-and-authentication/3-communication-library-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/30-appendix.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/31-scheduled-task.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/32-thread-pool.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/33-user-defined-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/34-backup-and-restoration.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/35-undo.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/36-DCF-parameters-settings.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/37-flashback.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/38-rollback-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/39-reserved-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/4-resource-consumption/1-memory.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/4-resource-consumption/2-disk-space.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/4-resource-consumption/3-kernel-resource-usage.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/4-resource-consumption/4-cost-based-vacuum-delay.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/4-resource-consumption/5-background-writer.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/4-resource-consumption/6-asynchronous-io-operations.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/40-AI-features.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/6-write-ahead-log/1-settings.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/6-write-ahead-log/2-checkpoints.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/6-write-ahead-log/3-log-replay.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/6-write-ahead-log/4-archiving.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/7-ha-replication/1-sending-server.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/7-ha-replication/2-primary-server.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/7-ha-replication/3-standby-server.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/8-mot.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/9-query-planning/1-optimizer-method-configuration.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/9-query-planning/2-optimizer-cost-constants.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/9-query-planning/3-genetic-query-optimizer.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/9-query-planning/4-other-optimizer-options.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/9-query-planning/introduction-to-query-planning.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/SQL-mode.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/cm-parameters/cm_agent.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/cm-parameters/cm_server.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/global-syscache-parameters.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/guc-parameters/guc-parameter-list.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/dblink-user-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/dolphin.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/orafce-user-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/pg_bulkload-user-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/pg_prewarm-user-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/pg_repack-user-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/pg_trgm-user-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/postgis-extension/postgis-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/postgis-extension/postgis-support-and-constraints.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/postgis-extension/using-postgis.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/wal2json-user-guide.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/oracle-plugins/whale.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.ARCHIVE_SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.CREATE_SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.CREATE_SNAPSHOT_INTERNAL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.MANAGE_SNAPSHOT_INTERNAL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.PREPARE_SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.PREPARE_SNAPSHOT_INTERNAL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.PUBLISH_SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.PURGE_SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.PURGE_SNAPSHOT_INTERNAL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.SAMPLE_SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/DB4AI.SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DB4AI-schema/overview-of-DB4AI-schema.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/DBE_PERF_overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_ALL_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_ALL_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_SYS_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_SYS_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_USER_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_USER_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STATIO_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STAT_DB_CU.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/GLOBAL_STAT_SESSION_CU.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_ALL_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_ALL_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_SYS_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_SYS_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_USER_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_USER_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/STATIO_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_ALL_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_ALL_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_SYS_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_SYS_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_USER_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_USER_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/cache-io/SUMMARY_STATIO_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/configuration/CONFIG_SETTINGS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/configuration/GLOBAL_CONFIG_SETTINGS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/FILE_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/FILE_REDO_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/GLOBAL_FILE_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/GLOBAL_FILE_REDO_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/GLOBAL_REL_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/LOCAL_REL_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/SUMMARY_FILE_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/SUMMARY_FILE_REDO_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/file/SUMMARY_REL_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/global-plancache/GLOBAL_PLANCACHE_CLEAN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/global-plancache/GLOBAL_PLANCACHE_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/global-plancache/global-plancache-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/instance/GLOBAL_INSTANCE_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/instance/INSTANCE_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/lock/GLOBAL_LOCKS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/lock/LOCKS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/memory/GLOBAL_MEMORY_NODE_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/memory/GLOBAL_SHARED_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/memory/GS_SHARED_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/memory/MEMORY_NODE_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_ALL_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_BAD_BLOCK.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_DATABASE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_DATABASE_CONFLICTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_SYS_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_USER_FUNCTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_USER_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_XACT_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_XACT_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_XACT_USER_FUNCTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/GLOBAL_STAT_XACT_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_ALL_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_BAD_BLOCK.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_DATABASE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_DATABASE_CONFLICTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_SYS_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_USER_FUNCTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_USER_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_XACT_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_XACT_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_XACT_USER_FUNCTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/STAT_XACT_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_ALL_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_BAD_BLOCK.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_DATABASE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_DATABASE_CONFLICTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_SYS_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_USER_FUNCTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_USER_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_XACT_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_XACT_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_XACT_USER_FUNCTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/object/SUMMARY_STAT_XACT_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/operator/GLOBAL_OPERATOR_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/operator/GLOBAL_OPERATOR_HISTORY_TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/operator/GLOBAL_OPERATOR_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/operator/OPERATOR_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/operator/OPERATOR_HISTORY_TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/operator/OPERATOR_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/os/GLOBAL_OS_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/os/GLOBAL_OS_THREADS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/os/OS_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/os/OS_THREADS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/GLOBAL_STATEMENT_COMPLEX_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/GLOBAL_STATEMENT_COMPLEX_HISTORY_TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/GLOBAL_STATEMENT_COMPLEX_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/GLOBAL_STATEMENT_COUNT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT_COMPLEX_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT_COMPLEX_HISTORY_TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT_COMPLEX_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT_COUNT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT_HISTORY_1.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT_RESPONSETIME_PERCENTILE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT_USER_COMPLEX_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/STATEMENT_WLMSTAT_COMPLEX_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/SUMMARY_STATEMENT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/query/SUMMARY_STATEMENT_COUNT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/rto/global_rto_status.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/GLOBAL_SESSION_MEMORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/GLOBAL_SESSION_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/GLOBAL_SESSION_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/GLOBAL_SESSION_STAT_ACTIVITY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/GLOBAL_SESSION_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/GLOBAL_THREADPOOL_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/GLOBAL_THREAD_WAIT_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/LOCAL_ACTIVE_SESSION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/LOCAL_THREADPOOL_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/SESSION_CPU_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/SESSION_MEMORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/SESSION_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/SESSION_MEMORY_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/SESSION_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/SESSION_STAT_ACTIVITY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/SESSION_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/STATEMENT_IOSTAT_COMPLEX_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/session-thread/THREAD_WAIT_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/transaction/GLOBAL_TRANSACTIONS_PREPARED_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/transaction/GLOBAL_TRANSACTIONS_RUNNING_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/transaction/SUMMARY_TRANSACTIONS_PREPARED_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/transaction/SUMMARY_TRANSACTIONS_RUNNING_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/transaction/TRANSACTIONS_PREPARED_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/transaction/TRANSACTIONS_RUNNING_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/BGWRITER_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/CLASS_VITAL_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_BGWRITER_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_CANDIDATE_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_CKPT_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_DOUBLE_WRITE_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_GET_BGWRITER_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_PAGEWRITER_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_RECORD_RESET_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_RECOVERY_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_REDO_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_REPLICATION_SLOTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_REPLICATION_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/GLOBAL_SINGLE_FLUSH_DW_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/REPLICATION_SLOTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/REPLICATION_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/SUMMARY_USER_LOGIN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/utility/USER_LOGIN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/wait-events/GLOBAL_WAIT_EVENTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/wait-events/WAIT_EVENTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload-manager/WLM_USER_RESOURCE_CONFIG.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload-manager/WLM_USER_RESOURCE_RUNTIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/GLOBAL_USER_TRANSACTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/GLOBAL_WORKLOAD_TRANSACTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/SUMMARY_WORKLOAD_SQL_COUNT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/SUMMARY_WORKLOAD_SQL_ELAPSE_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/SUMMARY_WORKLOAD_TRANSACTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/USER_TRANSACTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/WORKLOAD_SQL_COUNT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/WORKLOAD_SQL_ELAPSE_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PERF/workload/WORKLOAD_TRANSACTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.abort.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.add_breakpoint.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.attach.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.backtrace.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.continue.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.delete_breakpoint.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.disable_breakpoint.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.enable_breakpoint.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.finish.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.info_breakpoints.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.info_code.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.info_locals.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.local_debug_server_info.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.next.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.print_var.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.set_var.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.step.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.turn_off.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/DBE_PLDEBUGGER.turn_on.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEBUGGER-schema/overview-of-DBE_PLDEBUGGER-schema.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEVELOPER/DBE_PLDEVELOPER.gs_errors.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEVELOPER/DBE_PLDEVELOPER.gs_source.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/DBE_PLDEVELOPER/overview-of-DBE_PLDEVELOPER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/information-schema/1-information-schema-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/information-schema/2-_PG_FOREIGN_DATA_WRAPPERS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/information-schema/3-_PG_FOREIGN_SERVERS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/information-schema/4-_PG_FOREIGN_TABLE_COLUMNS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/information-schema/5-_PG_FOREIGN_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/information-schema/6-_PG_USER_MAPPINGS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/schema/information-schema/7-INFORMATION_SCHEMA_CATALOG_NAME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/1-mogdb-sql.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/10-dml-syntax-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/11-dcl-syntax-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/13-appendix/1-gin-indexes/1-introduction.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/13-appendix/1-gin-indexes/2-scalability.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/13-appendix/1-gin-indexes/3-implementation.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/13-appendix/1-gin-indexes/4-gin-tips-and-tricks.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/13-appendix/2-extended-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/13-appendix/3-extended-syntax.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/2-keywords.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/3-constant-and-macro.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/4-expressions/1-simple-expressions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/4-expressions/2-condition-expressions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/4-expressions/3-subquery-expressions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/4-expressions/4-array-expressions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/4-expressions/5-row-expressions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/5-type-conversion/1-type-conversion-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/5-type-conversion/2-operators.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/5-type-conversion/3-functions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/5-type-conversion/4-value-storage.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/5-type-conversion/5-union-case-and-related-constructs.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/1-introduction/1-full-text-retrieval.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/1-introduction/2-what-is-a-document.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/1-introduction/3-basic-text-matching.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/1-introduction/4-configurations.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/2-tables-and-indexes/1-searching-a-table.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/2-tables-and-indexes/2-creating-an-index.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/2-tables-and-indexes/3-constraints-on-index-use.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/3-controlling-text-search/1-parsing-documents.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/3-controlling-text-search/2-parsing-queries.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/3-controlling-text-search/3-ranking-search-results.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/3-controlling-text-search/4-highlighting-results.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/4-additional-features/1-manipulating-tsvector.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/4-additional-features/2-manipulating-queries.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/4-additional-features/3-rewriting-queries.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/4-additional-features/4-gathering-document-statistics.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/5-parser.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/6-dictionaries/1-dictionaries-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/6-dictionaries/2-stop-words.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/6-dictionaries/3-simple-dictionary.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/6-dictionaries/4-synonym-dictionary.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/6-dictionaries/5-thesaurus-dictionary.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/6-dictionaries/6-ispell-dictionary.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/6-dictionaries/7-snowball-dictionary.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/7-configuration-examples.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/8-testing-and-debugging-text-search/1-testing-a-configuration.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/8-testing-and-debugging-text-search/2-testing-a-parser.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/8-testing-and-debugging-text-search/3-testing-a-dictionary.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/6-full-text-search/9-limitations.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/7-system-operation.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/8-controlling-transactions.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-reference/9-ddl-syntax-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ABORT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-AGGREGATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-AUDIT-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-DATA-SOURCE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-DATABASE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-DEFAULT-PRIVILEGES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-DIRECTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-EXTENSION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-FOREIGN-TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-FUNCTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-GLOBAL-CONFIGURATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-GROUP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-INDEX.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-LANGUAGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-LARGE-OBJECT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-MASKING-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-MATERIALIZED-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-PACKAGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-PROCEDURE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-PUBLICATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-RESOURCE-LABEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-RESOURCE-POOL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-ROLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-ROW-LEVEL-SECURITY-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-RULE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-SCHEMA.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-SEQUENCE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-SERVER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-SESSION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-SUBSCRIPTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-SYNONYM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-SYSTEM-KILL-SESSION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-SYSTEM-SET.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-TABLE-PARTITION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-TABLE-SUBPARTITION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-TABLESPACE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-TEXT-SEARCH-CONFIGURATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-TEXT-SEARCH-DICTIONARY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-TRIGGER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-TYPE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-USER-MAPPING.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-USER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ALTER-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ANALYZE-ANALYSE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/BEGIN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CALL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CHECKPOINT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CLEAN-CONNECTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CLOSE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CLUSTER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/COMMENT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/COMMIT-END.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/COMMIT-PREPARED.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CONNECT-BY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/COPY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-AGGREGATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-AUDIT-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-CAST.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-CLIENT-MASTER-KEY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-COLUMN-ENCRYPTION-KEY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-DATA-SOURCE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-DATABASE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-DIRECTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-EXTENSION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-FOREIGN-TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-FUNCTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-GROUP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-INCREMENTAL-MATERIALIZED-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-INDEX.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-LANGUAGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-MASKING-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-MATERIALIZED-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-MODEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-OPERATOR.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-PACKAGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-PROCEDURE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-PUBLICATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-RESOURCE-LABEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-RESOURCE-POOL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-ROLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-ROW-LEVEL-SECURITY-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-RULE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-SCHEMA.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-SEQUENCE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-SERVER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-SUBSCRIPTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-SYNONYM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TABLE-AS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TABLE-PARTITION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TABLE-SUBPARTITION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TABLESPACE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TEXT-SEARCH-CONFIGURATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TEXT-SEARCH-DICTIONARY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TRIGGER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-TYPE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-USER-MAPPING.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-USER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CREATE-WEAK-PASSWORD-DICTIONARY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/CURSOR.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DEALLOCATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DECLARE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DELETE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-AGGREGATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-AUDIT-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-CAST.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-CLIENT-MASTER-KEY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-COLUMN-ENCRYPTION-KEY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-DATA-SOURCE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-DATABASE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-DIRECTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-EXTENSION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-FOREIGN-TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-FUNCTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-GLOBAL-CONFIGURATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-GROUP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-INDEX.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-LANGUAGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-MASKING-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-MATERIALIZED-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-MODEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-OPERATOR.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-OWNED.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-PACKAGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-PROCEDURE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-PUBLICATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-RESOURCE-LABEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-RESOURCE-POOL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-ROLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-ROW-LEVEL-SECURITY-POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-RULE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-SCHEMA.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-SEQUENCE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-SERVER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-SUBSCRIPTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-SYNONYM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-TABLESPACE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-TEXT-SEARCH-CONFIGURATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-TEXT-SEARCH-DICTIONARY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-TRIGGER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-TYPE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-USER-MAPPING.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-USER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/DROP-WEAK-PASSWORD-DICTIONARY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/EXECUTE-DIRECT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/EXECUTE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/EXPLAIN-PLAN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/EXPLAIN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/FETCH.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/GRANT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/INSERT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/LOCK.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/MERGE-INTO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/MOVE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/PREDICT-BY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/PREPARE-TRANSACTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/PREPARE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/PURGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/REASSIGN-OWNED.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/REFRESH-INCREMENTAL-MATERIALIZED-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/REFRESH-MATERIALIZED-VIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/REINDEX.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/RELEASE-SAVEPOINT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/RESET.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/REVOKE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ROLLBACK-PREPARED.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ROLLBACK-TO-SAVEPOINT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/ROLLBACK.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SAVEPOINT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SELECT-INTO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SELECT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SET-CONSTRAINTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SET-ROLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SET-SESSION-AUTHORIZATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SET-TRANSACTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SET.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SHOW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SHUTDOWN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/START-TRANSACTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/TIMECAPSULE-TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/TRUNCATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/UPDATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/VACUUM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/sql-syntax/VALUES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/1-numeric-data-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/10-text-search-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/11-uuid-type.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/12-json-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/13-HLL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/13.0-array-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/13.1-range.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/14-object-identifier-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/15-pseudo-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/16-data-types-supported-by-column-store-tables.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/17-xml-type.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/18-data-type-used-by-the-ledger-database.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/2-monetary.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/3-boolean-data-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/4-character-data-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/4.1-enumerated-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/5-binary-data-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/6-date-time-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/7-geometric.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/8-network-address.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/supported-data-types/9-bit-string-types.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/overview-of-system-catalogs-and-system-views.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_ASP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_AUDITING_POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_AUDITING_POLICY_ACCESS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_AUDITING_POLICY_FILTERS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_AUDITING_POLICY_PRIVILEGES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_CLIENT_GLOBAL_KEYS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_CLIENT_GLOBAL_KEYS_ARGS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_COLUMN_KEYS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_COLUMN_KEYS_ARGS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_DB_PRIVILEGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_ENCRYPTED_COLUMNS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_ENCRYPTED_PROC.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_GLOBAL_CHAIN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_GLOBAL_CONFIG.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_MASKING_POLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_MASKING_POLICY_ACTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_MASKING_POLICY_FILTERS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_MATVIEW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_MATVIEW_DEPENDENCY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_MODEL_WAREHOUSE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_OPT_MODEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_PACKAGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_POLICY_LABEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_RECYCLEBIN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_TXN_SNAPSHOT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_UID.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_WLM_EC_OPERATOR_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_WLM_INSTANCE_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_WLM_OPERATOR_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_WLM_PLAN_ENCODING_TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_WLM_PLAN_OPERATOR_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_WLM_SESSION_QUERY_INFO_ALL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/GS_WLM_USER_RESOURCE_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PGXC_CLASS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PGXC_GROUP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PGXC_NODE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PGXC_SLICE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_AGGREGATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_AM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_AMOP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_AMPROC.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_APP_WORKLOADGROUP_MAPPING.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_ATTRDEF.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_ATTRIBUTE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_AUTHID.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_AUTH_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_AUTH_MEMBERS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_CAST.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_CLASS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_COLLATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_CONSTRAINT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_CONVERSION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_DATABASE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_DB_ROLE_SETTING.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_DEFAULT_ACL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_DEPEND.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_DESCRIPTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_DIRECTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_ENUM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_EXTENSION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_EXTENSION_DATA_SOURCE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_FOREIGN_DATA_WRAPPER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_FOREIGN_SERVER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_FOREIGN_TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_HASHBUCKET.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_INDEX.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_INHERITS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_JOB.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_JOB_PROC.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_LANGUAGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_LARGEOBJECT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_LARGEOBJECT_METADATA.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_NAMESPACE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_OBJECT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_OPCLASS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_OPERATOR.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_OPFAMILY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_PARTITION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_PLTEMPLATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_PROC.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_PUBLICATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_PUBLICATION_REL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_RANGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_REPLICATION_ORIGIN.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_RESOURCE_POOL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_REWRITE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_RLSPOLICY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_SECLABEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_SHDEPEND.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_SHDESCRIPTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_SHSECLABEL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_STATISTIC.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_STATISTIC_EXT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_SUBSCRIPTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_SYNONYM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_TABLESPACE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_TRIGGER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_TS_CONFIG.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_TS_CONFIG_MAP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_TS_DICT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_TS_PARSER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_TS_TEMPLATE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_TYPE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_USER_MAPPING.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_USER_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PG_WORKLOAD_GROUP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/PLAN_TABLE_DATA.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-catalogs/STATEMENT_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/DV_SESSIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/DV_SESSION_LONGOPS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GET_GLOBAL_PREPARED_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_ASYNC_SUBMIT_SESSIONS_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_AUDITING.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_AUDITING_ACCESS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_AUDITING_PRIVILEGE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_CLUSTER_RESOURCE_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_DB_PRIVILEGES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_FILE_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_GSC_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_INSTANCE_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_LABELS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_LSC_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_MASKING.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_MATVIEWS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_OS_RUN_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_REDO_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_SESSION_CPU_STATISTICS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_SESSION_MEMORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_SESSION_MEMORY_CONTEXT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_SESSION_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_SESSION_MEMORY_STATISTICS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_SESSION_STAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_SESSION_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_SQL_COUNT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_STAT_SESSION_CU.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_THREAD_MEMORY_CONTEXT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_TOTAL_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_CGROUP_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_EC_OPERATOR_STATISTICS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_OPERATOR_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_OPERATOR_STATISTICS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_PLAN_OPERATOR_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_REBUILD_USER_RESOURCE_POOL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_RESOURCE_POOL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_SESSION_HISTORY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_SESSION_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_SESSION_INFO_ALL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_SESSION_STATISTICS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WLM_USER_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/GS_WRITE_TERM_LOG.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/MPP_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PGXC_PREPARED_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_AVAILABLE_EXTENSIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_AVAILABLE_EXTENSION_VERSIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_COMM_DELAY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_COMM_RECV_STREAM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_COMM_SEND_STREAM.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_COMM_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_CONTROL_GROUP_CONFIG.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_CURSORS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_EXT_STATS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_GET_INVALID_BACKENDS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_GET_SENDERS_CATCHUP_TIME.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_GROUP.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_GTT_ATTACHED_PIDS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_GTT_RELSTATS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_GTT_STATS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_LOCKS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_NODE_ENV.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_OS_THREADS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_PREPARED_STATEMENTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_PREPARED_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_PUBLICATION_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_REPLICATION_ORIGIN_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_REPLICATION_SLOTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_RLSPOLICIES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_ROLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_RULES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_RUNNING_XACTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_SECLABELS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_SESSION_IOSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_SESSION_WLMSTAT.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_SETTINGS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_SHADOW.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_ALL_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_ALL_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_SYS_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_SYS_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_USER_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_USER_SEQUENCES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATIO_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STATS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_ACTIVITY.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_ACTIVITY_NG.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_ALL_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_BAD_BLOCK.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_BGWRITER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_DATABASE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_DATABASE_CONFLICTS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_REPLICATION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_SUBSCRIPTION.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_SYS_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_USER_FUNCTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_USER_INDEXES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_XACT_ALL_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_XACT_SYS_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_XACT_USER_FUNCTIONS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_XACT_USER_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_TABLES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_TDE_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_THREAD_WAIT_STATUS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_TIMEZONE_ABBREVS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_TIMEZONE_NAMES.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_TOTAL_MEMORY_DETAIL.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_TOTAL_USER_RESOURCE_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_TOTAL_USER_RESOURCE_INFO_OID.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_USER.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_USER_MAPPINGS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_VARIABLE_INFO.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_VIEWS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PG_WLM_STATISTICS.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/system-catalogs-and-system-views/system-views/PLAN_TABLE.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/FAQ.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/client-tool/1-gsql.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/client-tool/client-tool.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/functions-of-mogdb-executable-scripts.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/0-gs_cgroup.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/1-gs_check.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/10-gs_ssh.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/2-gs_checkos.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/3-gs_checkperf.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/3.1-gs_clean.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/4-gs_collector.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/5-gs_dump.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/6-gs_dumpall.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/7-gs_guc.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/7.1-gs_encrypt.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/8-gs_om.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/9-gs_restore.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/gs_gucquery.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/server-tools/gs_watch.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/system-catalogs-and-views-supported-by-gs_collector.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tool-overview.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/1-gaussdb.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/10-gs_tar.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/11-gs_uninstall.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/12-gs_upgradectl.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/13-gs_expansion.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/14-gs_dropnode.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/15-gs_probackup.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/16-gstrace.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/17-kdb5_util.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/18-kadmin-local.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/19-kinit.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/2-gs_backup.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/20-klist.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/21-krb5kdc.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/22-kdestroy.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/23-pg_config.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/24-pg_controldata.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/24.1-pg_recvlogical.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/25-pg_resetxlog.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/26-pg_archivecleanup.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/27-pssh.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/28-pscp.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/29-transfer.py.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/3-gs_basebackup.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/4-gs_ctl.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/5-gs_initdb.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/6-gs_install.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/7-gs_postuninstall.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/8-gs_preinstall.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/9-gs_sshexkey.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/gs_install_plugin.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/tools-used-in-the-internal-system/gs_install_plugin_local.md create mode 100644 product/zh/docs-mogdb/v3.1/reference-guide/tool-reference/unified-database-management-tool.md create mode 100644 product/zh/docs-mogdb/v3.1/security-guide/security/1-client-access-authentication.md create mode 100644 product/zh/docs-mogdb/v3.1/security-guide/security/2-managing-users-and-their-permissions.md create mode 100644 product/zh/docs-mogdb/v3.1/security-guide/security/3-configuring-database-audit.md create mode 100644 product/zh/docs-mogdb/v3.1/security-guide/security/4-setting-encrypted-equality-query.md create mode 100644 product/zh/docs-mogdb/v3.1/security-guide/security/5-setting-a-ledger-database.md create mode 100644 product/zh/docs-mogdb/v3.1/security-guide/security/6-transparent-data-encryption.md create mode 100644 product/zh/docs-mogdb/v3.1/source-code-parsing.md create mode 100644 product/zh/docs-mogdb/v3.1/toc.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_about.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_ai-features.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_characteristic_description.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_common-faults-and-identification.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_communication-matrix.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_datatypes-and-sql.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_dev.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_error.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_extension-referecne.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_faqs.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_glossary.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_install.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_manage.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_parameters-and-tools.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_performance.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_quickstart.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_secure.md create mode 100644 product/zh/docs-mogdb/v3.1/toc_system-catalogs-and-functions.md diff --git a/product/zh/docs-mogdb/v3.1/AI-features/1-AI-features-overview.md b/product/zh/docs-mogdb/v3.1/AI-features/1-AI-features-overview.md new file mode 100644 index 00000000..3461b57a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/1-AI-features-overview.md @@ -0,0 +1,18 @@ +--- +title: AI特性概述 +summary: AI特性概述 +author: Guo Huan +date: 2021-05-19 +--- + +# AI特性概述 + +人工智能技术最早可以追溯到上世纪50年代,甚至比数据库系统的发展历史还要悠久。但是,由于各种各样客观因素的制约,在很长的一段时间内,人工智能技术并没有得到大规模的应用,甚至还经历了几次明显的低谷期。到了近些年,随着信息技术的进一步发展,从前限制人工智能发展的因素已经逐渐减弱,所谓的ABC(AI、Big data、Cloud computing)技术也随之而诞生。 + +AI与数据库结合是近些年的行业研究热点,MogDB较早地参与了该领域的探索,并取得了阶段性的成果。AI特性子模块名为DBMind,相对数据库其他功能更为独立,大致可分为AI4DB、DB4AI以及AI in DB三个部分。 + +- AI4DB就是指用人工智能技术优化数据库的性能,从而获得更好地执行表现;也可以通过人工智能的手段实现自治、免运维等。主要包括自调优、自诊断、自安全、自运维、自愈等子领域; +- DB4AI就是指打通数据库到人工智能应用的端到端流程,通过数据库来驱动AI任务,统一人工智能技术栈,达到开箱即用、高性能、节约成本等目的。例如通过SQL-like语句实现推荐系统、图像检索、时序预测等功能,充分发挥数据库的高并行、列存储等优势,既可以避免数据和碎片化存储的代价,又可以避免因信息泄漏造成的安全风险; +- AI in DB 就是对数据库内核进行修改,实现原有数据库架构模式下无法实现的功能,如利用AI算法改进数据库的优化器,实现更精确的代价估计等。 + +本章节所涉及的功能独立存在于数据库安装目录(`$GAUSSHOME`)的`bin/dbmind`目录中,各个子功能存在于dbmind的子目录components中。提供gs_dbmind命令行供用户调用。与此同时,对于数据库内置AI的功能(如DB4AI),以SQL语法和系统函数的形式呈现。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-best-practices.md b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-best-practices.md new file mode 100644 index 00000000..32da42e4 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-best-practices.md @@ -0,0 +1,32 @@ +--- +title: 最佳实践 +summary: 最佳实践 +author: Guo Huan +date: 2022-05-06 +--- + +# 最佳实践 + +相关参数解释参考表[GS_OPT_MODEL](../../../reference-guide/system-catalogs-and-system-views/system-catalogs/GS_OPT_MODEL.md)。 + +**表 1** + +| 模型参数 | 参数建议 | +| :------------ | :----------------------------------------------------------- | +| template_name | ‘rlstm’ | +| model_name | 自定义,如‘open_ai’,需满足unique约束。 | +| datname | 所服务database名称,如‘postgres’。 | +| ip | aiEngine-ip地址,如‘127.0.0.1’。 | +| port | aiEngine侦听端口,如‘5000’。 | +| max_epoch | 迭代次数,推荐较大数值,保证收敛效果,如‘2000’。 | +| learning_rate | (0, 1]浮点数,推荐较大的学习率,助于加快收敛速度。 | +| dim_red | 特征值降维系数:‘-1’:不采用PCA降维,全量特征;‘(0,1] ’区间浮点数:越小,训练维度越小,收敛速度越快,但影响训练准确率。 | +| hidden_units | 特征值维度较高时,建议适度增大此参数,提高模型复杂度,如 ‘64,128……’ | +| batch_size | 根据编码数据量,较大数据量推荐适度增大此参数,加快模型收敛,如‘256,512……’ | +| 其他参数 | 参考表[GS_OPT_MODEL](../../../reference-guide/system-catalogs-and-system-views/system-catalogs/GS_OPT_MODEL.md) | + +推荐参数配置: + +``` +INSERT INTO gs_opt_model values('rlstm', 'open_ai', 'postgres', '127.0.0.1', 5000, 2000,1, -1, 64, 512, 0 , false, false, '{S, T}', '{0,0}', '{0,0}', 'Text'); +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-environment-deployment.md b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-environment-deployment.md new file mode 100644 index 00000000..d9aeb90d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-environment-deployment.md @@ -0,0 +1,205 @@ +--- +title: 环境部署 +summary: 环境部署 +author: Guo Huan +date: 2022-05-06 +--- + +# 环境部署 + +## 前提条件 + +需要保证MogDB处于正常状态,用户通过身份验证成功登录MogDB;用户执行的SQL语法正确无报错,且不会导致数据库异常等;历史性能数据窗口内MogDB并发量稳定,表结构、表数量不变,数据量无突变,涉及查询性能的guc参数不变;进行预测时,需要保证模型已训练并收敛;AiEngine运行环境稳定。 + +## 请求样例 + +AiEngine进程与内核进程使用https发送请求进行通信,请求样例如下: + +```bash +curl -X POST -d '{"modelName":"modelname"}' -H 'Content-Type: application/json' https://IP-address:port/request-API +``` + +**表 1** : AI-Engine对外接口 + +| Request-API | 功能 | +| :------------- | :--------------------- | +| /check | 检查模型是否被正常拉起 | +| /configure | 设置模型参数 | +| /train | 模型训练 | +| /track_process | 查看模型训练日志 | +| /setup | 加载历史模型 | +| /predict | 模型预测 | + +## 证书生成 + +使用此功能前需使用openssl工具生成通信双方认证所需的证书,保证通信安全。 + +1. 搭建证书生成环境,证书文件保存路径为$GAUSSHOME/CA。 + + 拷贝证书生成脚本及相关文件 + + ```bash + cp path_to_predictor/install/ssl.sh $GAUSSHOME/ + cp path_to_predictor/install/ca_ext.txt $GAUSSHOME/ + ``` + + copy 配置文件openssl.cnf到$GAUSSHOME路径下 + + ```bash + cp $GAUSSHOME/share/om/openssl.cnf $GAUSSHOME/ + ``` + + 修改openssl.conf配置参数 + + ```bash + dir = $GAUSSHOME/CA/demoCA + default_md = sha256 + ``` + + 至此证书生成环境准备完成 + +2. 生成证书及密钥 + + ```bash + cd $GAUSSHOME + sh ssl.sh + ``` + + 根据提示设置密码,假如为Test@123: + + 密码要求至少3种不同类型字符,长度至少为8位 + + ```bash + Please enter your password: + ``` + + 根据提示输入选项: + + ```bash + Certificate Details: + Serial Number: 1 (0x1) + Validity + Not Before: May 15 08:32:44 2020 GMT + Not After : May 15 08:32:44 2021 GMT + Subject: + countryName = CN + stateOrProvinceName = SZ + organizationName = HW + organizationalUnitName = GS + commonName = CA + X509v3 extensions: + X509v3 Basic Constraints: + CA:TRUE + Certificate is to be certified until May 15 08:32:44 2021 GMT (365 days) + Sign the certificate? [y/n]:y + 1 out of 1 certificate requests certified, commit? [y/n]y + ``` + + 输入拉起AIEngine的IP地址,如IP为127.0.0.1: + + ```bash + Please enter your aiEngine IP: 127.0.0.1 + ``` + + 根据提示输入选项: + + ```bash + Certificate Details: + Serial Number: 2 (0x2) + Validity + Not Before: May 15 08:38:07 2020 GMT + Not After : May 13 08:38:07 2030 GMT + Subject: + countryName = CN + stateOrProvinceName = SZ + organizationName = HW + organizationalUnitName = GS + commonName = 127.0.0.1 + X509v3 extensions: + X509v3 Basic Constraints: + CA:FALSE + Certificate is to be certified until May 13 08:38:07 2030 GMT (3650 days) + Sign the certificate? [y/n]:y + 1 out of 1 certificate requests certified, commit? [y/n]y + ``` + + 输入启动MogDB IP地址,如IP为127.0.0.1: + + ```bash + Please enter your mogdb IP: 127.0.0.1 + ``` + + 根据提示输入选项: + + ```bash + Certificate Details: + Serial Number: 3 (0x3) + Validity + Not Before: May 15 08:41:46 2020 GMT + Not After : May 13 08:41:46 2030 GMT + Subject: + countryName = CN + stateOrProvinceName = SZ + organizationName = HW + organizationalUnitName = GS + commonName = 127.0.0.1 + X509v3 extensions: + X509v3 Basic Constraints: + CA:FALSE + Certificate is to be certified until May 13 08:41:46 2030 GMT (3650 days) + Sign the certificate? [y/n]:y + 1 out of 1 certificate requests certified, commit? [y/n]y + ``` + + 至此,相关证书及密钥已生成,($GAUSSHOME/CA)内容如下: + + ![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/intelligence-explain-1.png) + +## 环境准备 + +1. 将工具代码文件夹拷贝至目标环境 + + 假设安装路径为$INSTALL_FOLDER + + 假设目标环境路径为/home/ai_user : + + ```bash + scp -r $INSTALL_FOLDER/bin/dbmind/predictor ai_user@127.0.0.1:path_to_Predictor + ``` + +2. 拷贝CA证书文件夹至aiEngine环境中某路径下: + + ```bash + cp -r $GAUSSHOME/CA ai_user@127.0.0.1:path_to_CA + ``` + +3. 安装predictor/install/requirements(-gpu).txt工具(**该功能比较特殊,与其他AI功能不同,需要独立安装依赖**): + + ```bash + # 有GPU + pip install -r requirements-gpu.txt + # 无GPU + pip install -r requirements.txt + ``` + +## 拉起AiEngine + +1. 切换至aiEngine环境(即拷贝predictor的目标环境 ai_user): + + 设置predictor/python/settings.py 中的相关参数: + + ```bash + DEFAULT_FLASK_SERVER_HOST = '127.0.0.1' (aiEngine运行IP地址) + DEFAULT_FLASK_SERVER_PORT = '5000' (aiEngine运行端口号) + PATH_SSL = "path_to_CA" (CA文件夹路径) + ``` + +2. 运行aiEngine启动脚本: + + ```bash + python path_to_Predictor/python/run.py + ``` + + 此时,aiEngine即在相应端口保持拉起状态,等待内核侧时间预测功能的请求指令。 + + 至此,aiEngine工具部署完成。从内核中发起执行时间预测功能指令步骤,请参考[使用指导](intelligence-explain-user-guide.md)。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-faqs.md b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-faqs.md new file mode 100644 index 00000000..dfefab6b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-faqs.md @@ -0,0 +1,35 @@ +--- +title: 常见问题处理 +summary: 常见问题处理 +author: Guo Huan +date: 2022-05-06 +--- + +# 常见问题处理 + +## AI Engine配置问题 + +- **AiEngine启动失败**:请检查ip地址,端口是否可用;CA证书路径是否存在。 +- **发起请求AiEngine无响应**:请检查通信双方CA证书是否一致。 +- **训练,测试场景失败**:请检查模型文件保存路径是否存在;训练预测文件是否在正确下载。 +- **更换AiEngine-IP地址**:按照[证书生成](intelligence-explain-environment-deployment.md#证书生成)步骤重新生成证书,在生成证书及密钥中替换成相应的IP地址即可。 + +## 数据库内部报错问题 + +问题:AiEngine链接失败。 + +``` +ERROR: AI engine connection failed. +CONTEXT: referenced column: model_train_opt +``` + +处理方法:检查AIEngine是否正常拉起或重启AIEngine;检查通信双方CA证书是否一致;检查模型配置信息中的ip和端口是否匹配; + +问题:模型不存在。 + +``` +ERROR: OPT_Model not found for model name XXX +CONTEXT: referenced column: track_model_train_opt +``` + +处理方法:检查[GS_OPT_MODEL](../../../reference-guide/system-catalogs-and-system-views/system-catalogs/GS_OPT_MODEL.md)表中是否存在执行语句中“model_name”对应的模型;使用预测功能报错时,检查模型是否已被训练; diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-overview.md b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-overview.md new file mode 100644 index 00000000..06a96d01 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-overview.md @@ -0,0 +1,14 @@ +--- +title: 概述 +summary: 概述 +author: Guo Huan +date: 2022-05-06 +--- + +# 概述 + +本功能名为Predictor,是基于机器学习且具有在线学习能力的查询时间预测工具。通过不断学习数据库内收集的历史执行信息,实现计划的执行时间预测功能。 + +本特性需要拉起python进程AIEngine,用于模型的训练和推理。 + +该功能所在目录为$**GAUSSHOME**/bin/dbmind/components/predictor。由于该模块中某些功能涉及到相对复杂的搭建,因此,需要用户切换到该目录中寻找对应文件,并按照本章说明进行部署。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-user-guide.md b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-user-guide.md new file mode 100644 index 00000000..170cd46b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai-in-db/intelligence-explain/intelligence-explain-user-guide.md @@ -0,0 +1,207 @@ +--- +title: 使用指导 +summary: 使用指导 +author: Guo Huan +date: 2022-05-06 +--- + +# 使用指导 + +## 数据收集 + +1. 打开数据收集。 + + 1. 设置ActiveSQL operator信息相关参数: + + ``` + enable_resource_track=on + resource_track_level=operator + enable_resource_record=on + resource_track_cost=10(默认值为100000) + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: + > + > - resource_track_cost需设置为小于需要收集的查询总代价,满足条件的信息才能被收集。 + > - Cgroups功能正常加载。 + + 2. 信息收集: + + 执行业务查询语句。 + + 查看实时收集数据: + + ``` + select * from gs_wlm_plan_operator_history; + ``` + + 预期:满足resource_track_duration和resource_track_cost的作业被全量收集。 + +2. 关闭数据收集。 + + 1. 设置ActiveSQL operator信息相关参数: + + ``` + enable_resource_track=off 或 + resource_track_level=none 或 + resource_track_level=query + ``` + + 2. 执行业务查询语句。 + + 等待三分钟之后查看当前节点上的数据: + + ``` + select * from gs_wlm_plan_operator_info; + ``` + + 预期:所查表和视图无新增数据。 + +3. 数据持久化保存。 + + 1. 设置ActiveSQL operator信息相关参数: + + ``` + enable_resource_track=on + resource_track_level=operator + enable_resource_record=on + resource_track_duration=0(默认值为60s) + resource_track_cost=10(默认值为100000) + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: + > + > - resource_track_cost需设置为小于需要收集的查询总代价,满足条件的信息才能被收集 + > - Cgroups功能正常加载。 + + 2. 执行业务查询语句。 + + 等待三分钟之后查看当前节点上的数据: + + ``` + select * from gs_wlm_plan_operator_info; + ``` + + 预期:满足resource_track_duration和resource_track_cost的作业被全量收集。 + +## 模型管理(系统管理员用户) + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 模型管理操作需要在数据库正常的状态下进行。 + +1. 新增模型: + + INSERT INTO gs_opt_model values('……'); + + 示例: + + ``` + INSERT INTO gs_opt_model values('rlstm', 'model_name', 'datname', '127.0.0.1', 5000, 2000, 1, -1, 64, 512, 0 , false, false, '{S, T}', '{0,0}', '{0,0}', 'Text'); + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: + > + > - 具体模型参数设置请参考[GS_OPT_MODEL](../../../reference-guide/system-catalogs-and-system-views/system-catalogs/GS_OPT_MODEL.md)。 + > - 目前 “template_name” 列只支持 “rlstm”。 + > - “datname” 列请和用于模型使用和训练的数据库保持一致,否则无法使用。 + > - “model_name” 一列需要满足unique约束。 + > - 其他参数设置见产品文档[最佳实践](intelligence-explain-best-practices.md)部分。 + +2. 修改模型参数: + + ``` + UPDATE gs_opt_model SET = WHERE model_name = ; + ``` + +3. 删除模型: + + ``` + DELETE FROM gs_opt_model WHERE model_name = ; + ``` + +4. 查询现有模型及其状态: + + ``` + SELECT * FROM gs_opt_model; + ``` + +## 模型训练(系统管理员用户) + +1. 配置/添加模型训练参数:参考上一节模型管理(系统管理员用户)进行模型添加、模型参数修改,来指定训练参数。 + + 例: + + 模型添加: + + ``` + INSERT INTO gs_opt_model values('rlstm', 'default', 'postgres', '127.0.0.1', 5000, 2000, 1, -1, 64, 512, 0 , false, false, '{S, T}', '{0,0}', '{0,0}', 'Text'); + ``` + + 训练参数更新: + + ``` + UPDATE gs_opt_model SET = WHERE model_name = ; + ``` + +2. 前提条件为数据库状态正常且历史数据正常收集: + + 删除原有encoding数据: + + ``` + DELETE FROM gs_wlm_plan_encoding_table; + ``` + + 进行数据编码,需要指定数据库名: + + ``` + SELECT gather_encoding_info('postgres'); + ``` + + 开始训练: + + ``` + SELECT model_train_opt('rlstm', 'default'); + ``` + +3. 获取AI Engine侧模型训练日志相对路径: + + ``` + SELECT * FROM track_model_train_opt('rlstm', 'default'); + ``` + +## 模型预测 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 模型预测功能需在数据库状态正常、指定模型已被训练且收敛的条件下进行。 +> +> - 目前,模型训练参数的标签设置中需要包含“S”标签,explain中才可显示“p-time”预测值。 +> +> 例:INSERT INTO gs_opt_model values('rlstm', 'default', 'postgres', '127.0.0.1', 5000, 1000, 1, -1, 50, 500, 0 , false, false, '{**S**, T}', '{0,0}', '{0,0}', 'Text'); + +1. 调用explain接口: + + ``` + explain (analyze on, predictor ) + SELECT ... + ``` + + 预期结果: + + ``` + 例:Row Adapter (cost=110481.35..110481.35 rows=100 p-time=99..182 width=100) (actual time=375.158..375.160 rows=2 loops=1) + 其中,“p-time”列为标签预测值。 + ``` + +## 其他功能 + +1. 检查AiEngine是否可连接: + + ``` + MogDB=# select check_engine_status('aiEngine-ip-address',running-port); + ``` + +2. 查看模型对应日志在AiEngine侧的保存路径: + + ``` + MogDB=# select track_model_train_opt('template_name', 'model_name'); + ``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-1-x-tuner-overview.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-1-x-tuner-overview.md new file mode 100644 index 00000000..08e3bc2a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-1-x-tuner-overview.md @@ -0,0 +1,10 @@ +--- +title: 概述 +summary: 概述 +author: Guo Huan +date: 2021-05-19 +--- + +# 概述 + +X-Tuner是一款数据库集成的参数调优工具,通过结合深度强化学习和全局搜索算法等AI技术,实现在无需人工干预的情况下,获取最佳数据库参数配置。本功能不强制与数据库环境部署到一起,支持独立部署,脱离数据库安装环境独立运行。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-2-preparations.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-2-preparations.md new file mode 100644 index 00000000..4ae32ab8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-2-preparations.md @@ -0,0 +1,198 @@ +--- +title: 使用准备 +summary: 使用准备 +author: Guo Huan +date: 2021-05-19 +--- + +# 使用准备 + +
+ +## 前提条件与使用事项 + +- 数据库状态正常、客户端能够正常连接、且要求数据库内导入数据,以便调优程序可以执行benchmark测试调优效果。 +- 使用本工具需要指定登录到数据库的用户身份,要求该登录到数据库上的用户具有足够的权限,以便可以获得充足的数据库状态信息。 +- 使用登录到数据库宿主机上的Linux用户,需要将$**GAUSSHOME/bin**添加到PATH环境变量中,即能够直接运行gsql、gs_guc、gs_ctl等数据库运维工具。 +- 本工具支持以三种模式运行,其中tune和train模式要求用户配置好benchmark运行环境,并导入数据,本工具将会通过迭代运行benchmark来判断修改后的参数是否有性能提升。 +- recommend模式建议在数据库正在执行workload的过程中执行,以便获得更准确的实时workload信息。 +- 本工具默认带有TPC-C、TPC-H、TPC-DS以及sysbench的benchmark运行脚本样例,如果用户使用上述benchmark对数据库系统进行压力测试,则可以对上述配置文件进行适度修改或配置。如果需要适配用户自己的业务场景,需要您参照benchmark目录中的template.py文件编写驱动您自定义benchmark的脚本文件。 + +
+ +## 原理简介 + +调优程序是一个独立于数据库内核之外的工具,需要提供数据库及其所在实例的用户名和登录密码信息,以便控制数据库执行benchmark进行性能测试;在启动调优程序前,要求用户测试环境交互正常,能够正常跑通benchmark测试脚本、能够正常连接数据库。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 如果需要调优的参数中,包含重启数据库后才能使修改生效的参数,那么在调优过程中数据库将会重启多次。如果用户的数据库正在执行作业,请慎用train与tune模式。 + +调优程序X-Tuner包含三种运行模式,分别是: + +- recommend:通过用户指定的用户名等信息登录到数据库环境中,获取当前正在运行的workload特征信息,根据上述特征信息生成参数推荐报告。报告当前数据库中不合理的参数配置和潜在风险等;输出根据当前正在运行的workload行为和特征;输出推荐的参数配置。**该模式是秒级的,不涉及数据库的重启操作,其他模式可能需要反复重启数据库**。 +- train:通过用户提供的benchmark信息,不断地进行参数修改和benchmark的执行。通过反复的迭代过程,训练强化学习模型,以便用户在后面通过tune模式加载该模型进行调优。 +- tune:使用优化算法进行数据库参数的调优,当前支持两大类算法,一种是深度强化学习,另一种是全局搜索算法(全局优化算法)。深度强化学习模式要求先运行train模式,生成训练后的调优模型,而使用全局搜索算法则不需要提前进行训练,可以直接进行搜索调优。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: 如果在tune模式下,使用深度强化学习算法,要求必须有一个训练好的模型,且要求**训练该模型时的参数与进行调优时的参数列表(包括max与min)必须一致**。 + +**图 1** X-Tuner 结构图
+ +![X-Tuner-结构图](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/preparations-1.png) + +X-Tuner 的整体架构如图1 X-Tuner 结构图所示,系统可以分为: + +- DB侧:通过DB_Agent 模块对数据库实例进行抽象,通过该模块可以获取数据库内部的状态信息、当前数据库参数、以及设置数据库参数等。DB侧包括登录数据库环境使用的SSH连接。 +- 算法侧:用于调优的算法包,包括全局搜索算法(如贝叶斯优化、粒子群算法等)和深度强化学习(如DDPG); +- X-Tuner 主体逻辑模块:通过Enviroment模块进行封装,每一个step 就是一次调优过程。整个调优过程通过多个step进行迭代; +- benchmark:由用户指定的benchmark性能测试脚本,用于运行benchmark作业,通过跑分结果反映数据库系统性能优劣。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 应确保benchmark脚本跑分结果越大表示性能越好。 例如TPC-H这种衡量SQL语句整体执行时长的benchmark,可以通过取总体执行时间的相反数作为benchmark的输出分数。 + +
+ +## X-Tuner的运行和安装方法 + +执行下述命令即可获取xtuner功能帮助 + +``` +gs_dbmind component xtuner --help +``` + +用户可据此给定不同的命令行执行相应的功能。 + +
+ +## X-Tuner的配置文件说明 + +X-Tuner在运行前需要加载配置文件,用户可以通过**--help**命令查看默认加载的配置文件绝对路径: + +```bash +... + -x TUNER_CONFIG_FILE, --tuner-config-file TUNER_CONFIG_FILE + This is the path of the core configuration file of the + X-Tuner. You can specify the path of the new + configuration file. The default path is /path/to/xtuner/xtuner.conf. + You can modify the configuration file to control the + tuning process. +... +``` + +修改配置文件的配置项可以指引X-Tuner 执行不同的动作,用户可以根据自己的不同需求来修改配置文件的内容,配置文件的配置项说明详见[命令参考](1-5-command-reference.md)页面中的表2。如果需要修改配置文件的加载路径,则可以通过选**-x**命令行选项来指定。 + +
+ +## Benchmark的选择与配置 + +Benchmark的驱动脚本存放路径为X-Tuner目录(即**$GAUSSHOME**/bin/dbmind/components/xtuner,下同)的子目录benchmark中。X-Tuner自带常用的benchmark驱动脚本,例如基于时间周期的探测脚本(**默认**)、TPC-C、TPC-H等。X-Tuner通过调用benchmark/__init__.py文件中**get_benchmark_instance()**命令来加载不同的benchmark驱动脚本,获取benchmark驱动实例。其中,benchmark驱动脚本的格式说明如下: + +- 驱动脚本文件名:表示benchmark的名字,该名字用于表示驱动脚本的唯一性,可通过在X-Tuner 的配置文件中的配置项**benchmark_script**来指定选择加载哪个benchmark驱动脚本。 +- 驱动脚本内容三要素:path变量、cmd变量以及run函数。 + +下面分别介绍驱动脚本的内容三要素: + +1. path 变量:表示benchmark脚本的存放地址,可以直接在驱动脚本中修改,也可以通过配置文件的 benchmark_path 配置项来指定。 + +2. cmd 变量:表示执行benchmark 脚本需要运行的命令,可以直接在驱动脚本中修改,也可以通过配置文件的 benchmark_cmd 配置项来指定。cmd中的文本允许使用占位符,用于获取某些运行cmd命令时的必要信息,使用示例参见TPC-H驱动脚本示例。这些占位符包括: + + - {host}:数据库宿主机的IP地址 + - {port}:数据库实例的侦听端口号 + - {user}:登录数据库系统上的用户名 + - {password}:与登录数据库系统上的用户相匹配的密码 + - {db}:正在进行调优的数据库名 + +3. run函数:该函数的函数签名为: + + ```java + def run(remote_server, local_host) -> float: + ``` + + 其中,返回数据类型为float,表示benchmark执行后的评估分数值,要求该值越大表示性能越好,例如使用TPC-C跑分结果tpmC即可作为返回值,TPC-H的全部SQL语句执行总时间的相反数(取相反数后可保证返回值越大则性能越好)也可作为返回值。 + + remote_server 变量是X-Tuner 程序传递给脚本使用的远端主机(数据库宿主机)的shell命令接口,local_host 变量是X-Tuner 程序传递给脚本使用的本地主机(运行X-Tuner脚本的主机)的shell命令接口。上述shell命令接口提供的方法包括: + + ``` + exec_command_sync(command, timeout) + 功能:该方法用于在主机上执行shell命令。 + 参数列表: + command 必选,数据类型可以是str, 以及元素为str类型的list或tuple; + timeout 可选,表示命令执行的超时时长,单位是秒。 + 返回值: + 返回二元组 (stdout, stderr),stdout表示标准输出流结果,stderr表示标准错误流结果,数据类型均为str. + ``` + + ``` + exit_status + 功能:该属性表示最近一条shell命令执行后的退出状态码(exit status code)。 + 说明:一般情况,退出状态码为0表示执行正常,非0表示存在错误。 + ``` + +Benchmark驱动脚本示例说明 + +1. TPC-C 驱动脚本 + + ``` + from tuner.exceptions import ExecutionError + + # WARN: You need to download the benchmark-sql test tool to the system, + # replace the PostgreSQL JDBC driver with the openGauss driver, + # and configure the benchmark-sql configuration file. + # The program starts the test by running the following command: + path = '/path/to/benchmarksql/run' # TPC-C测试脚本benchmark-sql 的存放路径 + cmd = "./runBenchmark.sh props.gs" # 自定义一个名为 props.gs 的benchmark-sql测试配置文件 + + + def run(remote_server, local_host): + # 切换到 TPC-C 脚本目录下,清除历史错误日志,然后运行测试命令。 + # 此处最好等待几秒钟,因为benchmark-sql 测试脚本生成最终测试报告是通过一个shell脚本实现的,整个过程会有延迟, + # 为了保证能够获取到最终的tpmC数值报告,我们这里选择等待3秒钟。 + stdout, stderr = remote_server.exec_command_sync(['cd %s' % path, 'rm -rf benchmarksql-error.log', cmd, 'sleep 3']) + # 如果标准错误流中有数据,则报异常退出。 + if len(stderr) > 0: + raise ExecutionError(stderr) + + # 寻找最终tpmC结果 + tpmC = None + split_string = stdout.split() # 对标准输出流结果进行分词。 + for i, st in enumerate(split_string): + # 在5.0版本的benchmark-sql中,tpmC最终测试结果数值在 ‘(NewOrders)’关键字的后两位,正常情况下,找到该字段后直接返回即可。 + if "(NewOrders)" in st: + tpmC = split_string[i + 2] + break + stdout, stderr = remote_server.exec_command_sync( + "cat %s/benchmarksql-error.log" % path) + nb_err = stdout.count("ERROR:") # 判断整个benchmark运行过程中,是否有报错,记录报错的错误数 + return float(tpmC) - 10 * nb_err # 这里将报错的错误数作为一个惩罚项,惩罚系数为10,越高的惩罚系数表示越看中报错的数量. + + ``` + +2. TPC-H驱动脚本 + + ``` + import time + + from tuner.exceptions import ExecutionError + + # WARN: You need to import data into the database and SQL statements in the following path will be executed. + # The program automatically collects the total execution duration of these SQL statements. + path = '/path/to/tpch/queries' # 存放TPC-H测试用的SQL脚本目录 + cmd = "gsql -U {user} -W {password} -d {db} -p {port} -f {file}" # 需要运行TPC-H测试脚本的命令,一般使用'gsql -f 脚本文件' 来运行 + + + def run(remote_server, local_host): + # 遍历当前目录下所有的测试用例文件名 + find_file_cmd = "find . -type f -name '*.sql'" + stdout, stderr = remote_server.exec_command_sync(['cd %s' % path, find_file_cmd]) + if len(stderr) > 0: + raise ExecutionError(stderr) + files = stdout.strip().split('\n') + time_start = time.time() + for file in files: + # 使用 file 变量替换 {file},然后执行该命令行。 + perform_cmd = cmd.format(file=file) + stdout, stderr = remote_server.exec_command_sync(['cd %s' % path, perform_cmd]) + if len(stderr) > 0: + print(stderr) + # 代价为全部测试用例的执行总时长 + cost = time.time() - time_start + # 取相反数,适配run 函数的定义:返回结果越大表示性能越好。 + return - cost + ``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-3-examples.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-3-examples.md new file mode 100644 index 00000000..388b5f41 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-3-examples.md @@ -0,0 +1,162 @@ +--- +title: 使用示例 +summary: 使用示例 +author: Guo Huan +date: 2021-05-19 +--- + +# 使用示例 + +X-Tuner支持三种模式,分别是获取参数诊断报告的recommend模式、训练强化学习模型的train模式、以及使用算法进行调优的tune模式。上述三种模式可以通过命令行参数来区别,通过配置文件来指定具体的细节。 + +
+ +## 配置数据库连接信息 + +三种模式连接数据库的配置项是相同的,有两种方式:一种是直接通过命令行输入详细的连接信息,另一种是通过JSON格式的配置文件输入,下面分别对两种指定数据库连接信息的方法进行说明。 + +1. 通过命令行指定: + + 分别传递 -db-name -db-user -port -host -host-user 参数,可选 -host-ssh-port 参数,例如: + + ```bash + gs_dbmind component xtuner recommend --db-name postgres --db-user omm --port 5678 --host 192.168.1.100 --host-user omm + ``` + +2. 通过JSON格式的连接信息配置文件指定: + + JSON配置文件的示例如下,并假设文件名为connection.json: + + ```json + { + "db_name": "mogdb", # 数据库名 + "db_user": "dba", # 登录到数据库上的用户名 + "host": "127.0.0.1", # 数据库宿主机的IP地址 + "host_user": "dba", # 登录到数据库宿主机的用户名 + "port": 5432, # 数据库的侦听端口号 + "ssh_port": 22 # 数据库宿主机的SSH侦听端口号 + } + ``` + + 则可通过 -f connection.json 传递。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 为了防止密码泄露,配置文件和命令行参数中默认都不包含密码信息,用户在输入上述连接信息后,程序会采用交互式的方式要求用户输数据库密码以及操作系统登录用户的密码。 + +
+ +## recommend模式使用示例 + +对recommend模式生效的配置项为scenario,若为auto,则自动检测workload类型。 + +执行下述命令,获取诊断结果: + +```bash +gs_dbmind component xtuner recommend -f connection.json +``` + +则可以生成诊断报告如下: + +**图 1** recommend 模式生成的报告示意图 + +![recommend-模式生成的报告示意图](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/examples-1.png) + +在上述报告中,推荐了该环境上的数据库参数配置,并进行了风险提示。报告同时生成了当前workload的特征信息,其中有几个特征是比较有参考意义的: + +- temp_file_size:产生的临时文件数量,如果该结果大于0,则表明系统使用了临时文件。使用过多的临时文件会导致性能不佳,如果可能的话,需要提高work_mem参数的配置。 +- cache_hit_rate:shared_buffer 的缓存命中率,表明当前workload使用缓存的效率。 +- read_write_ratio:数据库作业的读写比例。 +- search_modify_ratio:数据库作业的查询与修改数据的比例。 +- ap_index:表明当前workload的AP指数,取值范围是0到10,该数值越大,表明越偏向于数据分析与检索。 +- workload_type:根据数据库统计信息,推测当前负载类型,分为AP、TP以及HTAP三种类型。 +- checkpoint_avg_sync_time:数据库在checkpoint 时,平均每次同步刷新数据到磁盘的时长,单位是毫秒。 +- load_average:平均**每个CPU核心**在1分钟、5分钟以及15分钟内的负载。一般地,该数值在1左右表明当前硬件比较匹配workload、在3左右表明运行当前作业压力比较大,大于5则表示当前硬件环境运行该workload压力过大(此时一般建议减少负载或升级硬件)。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 由于某些系统表会一直记录统计信息,这可能会对负载特征识别造成干扰,因此建议最好先清空某些系统表的统计信息,运行一段时间的workload后再使用recommend模式进行诊断,以便获得更准确的结果。清除统计信息的方法为: +> +> ``` +> select pg_stat_reset_shared('bgwriter'); +> select pg_stat_reset(); +> ``` +> +> - recommend模式会读取数据库中的pg\_stat\_database以及pg\_stat\_bgwriter等系统表中的信息,需要登录到数据库上的用户具有足够的权限(建议为**管理员权限**,可通过alter user username sysadmin;授予username相应的权限)。 + +
+ +## train 模式使用示例 + +该模式是用来训练深度强化学习模型的,与该模式有关的配置项为: + +- rl_algorithm:用于训练强化学习模型的算法,当前支持设置为ddpg。 + +- rl_model_path:训练后生成的强化学习模型保存路径。 + +- rl_steps:训练过程的最大迭代步数。 + +- max_episode_steps:每个回合的最大步数。 + +- scenario:明确指定的workload类型,如果为auto则为自动判断。在不同模式下,推荐的调优参数列表也不一样。 + +- tuning_list:**用户指定需要调哪些参数,如果不指定,则根据workload类型自动推荐应该调的参数列表。**如需指定,则tuning_list 表示调优列表文件的路径。一个调优列表配置文件的文件内容示例如下: + + ```json + { + "work_mem": { + "default": 65536, + "min": 65536, + "max": 655360, + "type": "int", + "restart": false + }, + "shared_buffers": { + "default": 32000, + "min": 16000, + "max": 64000, + "type": "int", + "restart": true + }, + "random_page_cost": { + "default": 4.0, + "min": 1.0, + "max": 4.0, + "type": "float", + "restart": false + }, + "enable_nestloop": { + "default": true, + "type": "bool", + "restart": false + } + } + ``` + +待上述配置项配置完成后,可以通过下述命令启动训练: + +```bash +gs_dbmind component xtuner train -f connection.json +``` + +训练完成后,会在配置项rl_model_path指定的目录中生成模型文件。 + +
+ +## tune 模式使用示例 + +tune模式支持多种算法,包括基于强化学习(Reinforcement Learning, RL)的DDPG算法、基于全局搜索算法(Global OPtimization algorithm, GOP)算法的贝叶斯优化算法(Bayesian Optimization)以及粒子群算法(Particle Swarm Optimization, PSO)。 + +与tune模式相关的配置项为: + +- tune_strategy: 指定选择哪种算法进行调优,支持rl(使用强化学习模型进行调优)、gop (使用全局搜索算法)以及 auto(自动选择)。若该参数设置为rl,则rl相关的配置项生效。除前文提到过的train模式下生效的配置项外,test_episode配置项也生效,该配置项表明调优过程的最大回合数,该参数直接影响了调优过程的执行时间(一般地,数值越大越耗时)。 +- gop_algorithm: 选择何种全局搜索算法,支持bayes以及pso。 +- max_iterations: 最大迭代轮次,数值越高搜索时间越长,效果往往越好。 +- particle_nums: 在PSO算法上生效,表示粒子数。 +- scenario 与 tuning_list 见上文 train 模式中的描述。 + +待上述配置项配置完成后,可以通过下述命令启动调优: + +```bash +gs_dbmind component xtuner tune -f connection.json +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** 在使用tune和train模式前,用户需要先导入benchmark所需数据并检查benchmark能否正常跑通。调优过程结束后,调优程序会自动恢复调优前的数据库参数配置。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-4-obtaining-help-information.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-4-obtaining-help-information.md new file mode 100644 index 00000000..5d050c2d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-4-obtaining-help-information.md @@ -0,0 +1,58 @@ +--- +title: 获取帮助 +summary: 获取帮助 +author: Guo Huan +date: 2021-05-19 +--- + +# 获取帮助 + +启动调优程序之前,可以通过如下命令获取帮助信息: + +```bash +gs_dbmind component xtuner --help +``` + +输出帮助信息结果如下: + +```bash +usage: [-h] [--db-name DB_NAME] [--db-user DB_USER] [--port PORT] + [--host HOST] [--host-user HOST_USER] + [--host-ssh-port HOST_SSH_PORT] [-f DB_CONFIG_FILE] + [-x TUNER_CONFIG_FILE] [-v] + {train,tune,recommend} + +X-Tuner: a self-tuning tool integrated by MogDB. + +positional arguments: + {train,tune,recommend} + Train a reinforcement learning model or tune database + by model. And also can recommend best_knobs according + to your workload. + +optional arguments: + -h, --help show this help message and exit + -f DB_CONFIG_FILE, --db-config-file DB_CONFIG_FILE + You can pass a path of configuration file otherwise + you should enter database information by command + arguments manually. Please see the template file + share/server.json.template. + -x TUNER_CONFIG_FILE, --tuner-config-file TUNER_CONFIG_FILE + This is the path of the core configuration file of the + X-Tuner. You can specify the path of the new + configuration file. The default path is xtuner.conf. + You can modify the configuration file to control the + tuning process. + -v, --version show program's version number and exit + +Database Connection Information: + --db-name DB_NAME The name of database where your workload running on. + --db-user DB_USER Use this user to login your database. Note that the + user must have sufficient permissions. + --port PORT Use this port to connect with the database. + --host HOST The IP address of your database installation host. + --host-user HOST_USER + The login user of your database installation host. + --host-ssh-port HOST_SSH_PORT + The SSH port of your database installation host. +``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-5-command-reference.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-5-command-reference.md new file mode 100644 index 00000000..56ccac39 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-5-command-reference.md @@ -0,0 +1,50 @@ +--- +title: 命令参考 +summary: 命令参考 +author: Guo Huan +date: 2021-05-19 +--- + +# 命令参考 + +**表 1** 命令行参数 + +| 参数 | 参数说明 | 取值范围 | +| :---------------------- | :----------------------------------------------------------- | :--------------------- | +| mode | 指定调优程序运行的模式 | train,tune,recommend | +| --tuner-config-file, -x | X-Tuner的核心参数配置文件路径,默认路径为安装目录下的xtuner.conf | - | +| --db-config-file, -f | 调优程序的用于登录到数据库宿主机上的连接信息配置文件路径,若通过该文件配置数据库连接信息,则下述数据库连接信息可省略 | - | +| --db-name | 指定需要调优的数据库名 | - | +| --db-user | 指定以何用户身份登陆到调优的数据库上 | - | +| --port | 数据库的侦听端口 | - | +| --host | 数据库实例的宿主机IP | - | +| --host-user | 指定以何用户身份登陆到数据库实例的宿主机上,要求改用户名的环境变量中可以找到gsql、gs_ctl等数据库运维工具。 | - | +| --host-ssh-port | 数据库实例所在宿主机的SSH端口号,可选,默认为22 | - | +| --help, -h | 返回帮助信息 | - | +| --version, -v | 返回当前工具版本号 | - | + +**表 2** 配置文件中的参数详解 + +| 参数名 | 参数说明 | 取值范围 | +| :-------------------- | :----------------------------------------------------------- | :---------------------------- | +| logfile | 生成的日志存放路径 | - | +| output_tuning_result | 可选,调优结果的保存路径 | - | +| verbose | 是否打印详情 | on, off | +| recorder_file | 调优中间信息的记录日志存放路径 | - | +| tune_strategy | 调优模式下采取哪种策略 | rl, gop, auto | +| drop_cache | 是否在每一个迭代轮次中进行drop cache,drop cache可以使benchmark跑分结果更加稳定。若启动该参数,则需要将登录的系统用户加入到 /etc/sudoers 列表中,同时为其增加**NOPASSWD**权限(由于该权限可能过高,建议临时启用该权限,调优结束后关闭)。 | on, off | +| used_mem_penalty_term | 数据库使用总内存的惩罚系数,用于防止通过无限量占用内存而换取的性能表现。该数值越大,惩罚力度越大。 | 建议0 ~ 1 | +| rl_algorithm | 选择何种RL算法 | ddpg | +| rl_model_path | RL模型保存或读取路径,包括保存目录名与文件名前缀。在train模式下该路径用于保存模型,在tune模式下则用于读取模型文件 | - | +| rl_steps | 深度强化学习算法迭代的步数 | - | +| max_episode_steps | 每个回合的最大迭代步数 | - | +| test_episode | 使用RL算法进行调优模式的回合数 | - | +| gop_algorithm | 采取何种全局搜索算法 | bayes, pso | +| max_iterations | 全局搜索算法的最大迭代轮次(并非确定数值,可能会根据实际情况多跑若干轮) | - | +| particle_nums | PSO算法下的粒子数量 | - | +| benchmark_script | 使用何种benchmark驱动脚本,该选项指定加载benchmark路径下同名文件,默认支持TPC-C、TPC-H等典型benchmark | tpcc, tpch, tpcds, sysbench … | +| benchmark_path | benchmark脚本的存储路径,若没有配置该选项,则使用benchmark驱动脚本中的配置 | - | +| benchmark_cmd | 启动benchmark脚本的命令,若没有配置该选项,则使用benchmark驱动脚本中的配置 | - | +| benchmark_period | 仅对period benchmark有效,表明整个benchmark的测试周期是多少,单位是秒 | - | +| scenario | 用户指定的当前workload所属的类型 | tp, ap, htap | +| tuning_list | 准备调优的参数列表文件,可参考share/knobs.json.template文件 | - | diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-6-Troubleshooting.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-6-Troubleshooting.md new file mode 100644 index 00000000..23b5b4e7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/1-x-tuner-parameter-optimization-and-diagnosis/1-6-Troubleshooting.md @@ -0,0 +1,13 @@ +--- +title: 常见问题处理 +summary: 常见问题处理 +author: Guo Huan +date: 2021-05-19 +--- + +# 常见问题处理 + +- 数据库实例连接失败:请检查数据库实例的情况,是否数据库实例出现了问题或安全权限配置(pg_hba.conf文件中的配置项)不正确。 +- 重启失败:请检查数据库实例健康情况,确保数据库实例工作正常; +- 跑TPC-C作业时发现性能越来越慢:TPC-C等高并发场景下的压力测试,往往伴随着大量的数据修改。由于每一次测试并非是幂等的(TPC-C数据库数据量的增加、没有进行vacuum full清理掉失效元组、数据库没有触发checkpoint、没有进行drop cache等),因此一般建议TPC-C等伴随着较多数据写入的benchmark应该每隔一段时间(视具体并发量、执行时长的不同而异)重新导入一次数据,比较简单的方法是备份$PGDATA目录。 +- TPC-C跑作业时,TPC-C驱动脚本报异常 “TypeError: float() argument must be a string or a number, not 'NoneType'”(不能将None转换为float类型):这是因为没有获取到TPC-C的压测返回结果,造成该问题的原因比较多,请首先手动检测是否能够跑通TPC-C并能够获取返回结果。若无上述问题,则建议将TPC-C驱动脚本中的命令列表中的 “sleep” 命令延迟时间设得更大一些。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-1-single-query-index-recommendation.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-1-single-query-index-recommendation.md new file mode 100644 index 00000000..4c079d93 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-1-single-query-index-recommendation.md @@ -0,0 +1,71 @@ +--- +title: 单query索引推荐 +summary: 单query索引推荐 +author: Guo Huan +date: 2021-05-19 +--- + +# 单query索引推荐 + +单query索引推荐功能支持用户在数据库中直接进行操作,本功能基于查询语句的语义信息和数据库的统计信息,对用户输入的单条查询语句生成推荐的索引。本功能涉及的函数接口如下。 + +**表 1** 单query索引推荐功能的接口 + +| 函数名 | 参数 | 功能 | +| :-------------- | :------------ | :----------------------------- | +| gs_index_advise | SQL语句字符串 | 针对单条查询语句生成推荐索引。 | + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 本功能仅支持单条SELECT类型的语句,不支持其他类型的SQL语句。 +> - 本功能暂不支持分区表、列存表、段页式表、普通视图、物化视图、全局临时表以及密态数据库。 + +
+ +## 使用方法 + +使用上述函数,获取针对该query生成的推荐索引,推荐结果由索引的表名和列名组成。 + +例如: + +```sql +mogdb=> select "table", "column" from gs_index_advise('SELECT c_discount from bmsql_customer where c_w_id = 10'); + table | column +----------------+---------- + bmsql_customer | (c_w_id) +(1 row) +``` + +上述结果表明:应当在 bmsql_customer 的 c_w_id 列上创建索引,例如可以通过下述SQL语句创建索引: + +```sql +CREATE INDEX idx on bmsql_customer(c_w_id); +``` + +某些SQL语句,也可能被推荐创建联合索引,例如: + +```sql +MogDB=# select "table", "column" from gs_index_advise('select name, age, sex from t1 where age >= 18 and age < 35 and sex = ''f'';'); + table | column +-------+------------ + t1 | (age, sex) +(1 row) +``` + +则上述语句表明应该在表 t1 上创建一个联合索引 (age, sex), 则可以通过下述命令创建: + +```sql +CREATE INDEX idx1 on t1(age, sex); +``` + +针对分区表可推荐具体索引类型,例如: + +```sql +MogDB=# select "table", "column", "indextype" from gs_index_advise('select name, age, sex from range_table where age = 20;'); + table | column | indextype +-------+--------+----------- + t1 | age | global +(1 row) +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 系统函数 gs_index_advise() 的参数是文本型,如果参数中存在如单引号(') 等特殊字符,可以使用单引号(') 进行转义,可参考上述示例。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-2-virtual-index.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-2-virtual-index.md new file mode 100644 index 00000000..a9ae4e19 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-2-virtual-index.md @@ -0,0 +1,125 @@ +--- +title: 虚拟索引 +summary: 虚拟索引 +author: Guo Huan +date: 2021-05-19 +--- + +# 虚拟索引 + +虚拟索引功能支持用户在数据库中直接进行操作,本功能将模拟真实索引的建立,避免真实索引创建所需的时间和空间开销,用户基于虚拟索引,可通过优化器评估该索引对指定查询语句的代价影响。 + +本功能涉及的系统函数接口如下表所示: + +**表 1** 虚拟索引功能的接口 + +| 函数名 | 参数 | 功能 | +| :------------------- | :------------------- | :------------------------------- | +| hypopg_create_index | 创建索引语句的字符串 | 创建虚拟索引。 | +| hypopg_display_index | 无 | 显示所有创建的虚拟索引信息。 | +| hypopg_drop_index | 索引的oid | 删除指定的虚拟索引。 | +| hypopg_reset_index | 无 | 清除所有虚拟索引。 | +| hypopg_estimate_size | 索引的oid | 估计指定索引创建所需的空间大小。 | + +本功能涉及的GUC参数如下: + +**表 2** 虚拟索引功能的GUC参数 + +| 参数名 | 功能 | 默认值 | +| :---------------- | :------------------- | :----- | +| enable_hypo_index | 是否开启虚拟索引功能 | off | + +
+ +## 使用步骤 + +1. 使用函数hypopg_create_index创建虚拟索引。例如: + + ```sql + mogdb=> select * from hypopg_create_index('create index on bmsql_customer(c_w_id)'); + indexrelid | indexname + ------------+------------------------------------- + 329726 | <329726>btree_bmsql_customer_c_w_id + (1 row) + ``` + +2. 开启GUC参数enable_hypo_index,该参数控制数据库的优化器进行EXPLAIN时是否考虑创建的虚拟索引。通过对特定的查询语句执行explain,用户可根据优化器给出的执行计划评估该索引是否能够提升该查询语句的执行效率。例如: + + ```sql + mogdb=> set enable_hypo_index = on; + SET + ``` + + 开启GUC参数前,执行EXPLAIN + 查询语句: + + ```sql + mogdb=> explain SELECT c_discount from bmsql_customer where c_w_id = 10; + QUERY PLAN + ---------------------------------------------------------------------- + Seq Scan on bmsql_customer (cost=0.00..52963.06 rows=31224 width=4) + Filter: (c_w_id = 10) + (2 rows) + ``` + + 开启GUC参数后,执行EXPLAIN + 查询语句: + + ```sql + mogdb=> explain SELECT c_discount from bmsql_customer where c_w_id = 10; + QUERY PLAN + ------------------------------------------------------------------------------------------------------------------ + [Bypass] + Index Scan using <329726>btree_bmsql_customer_c_w_id on bmsql_customer (cost=0.00..39678.69 rows=31224 width=4) + Index Cond: (c_w_id = 10) + (3 rows) + ``` + + 通过对比两个执行计划可以观察到,该索引预计会降低指定查询语句的执行代价,用户可考虑创建对应的真实索引。 + +3. (可选)使用函数hypopg_display_index展示所有创建过的虚拟索引。例如: + + ```sql + mogdb=> select * from hypopg_display_index(); + indexname | indexrelid | table | column + --------------------------------------------+------------+----------------+------------------ + <329726>btree_bmsql_customer_c_w_id | 329726 | bmsql_customer | (c_w_id) + <329729>btree_bmsql_customer_c_d_id_c_w_id | 329729 | bmsql_customer | (c_d_id, c_w_id) + (2 rows) + ``` + +4. (可选)使用函数hypopg_estimate_size估计虚拟索引创建所需的空间大小(单位:字节)。例如: + + ```sql + mogdb=> select * from hypopg_estimate_size(329730); + hypopg_estimate_size + ---------------------- + 15687680 + (1 row) + ``` + +5. 删除虚拟索引。 + + 使用函数hypopg_drop_index删除指定oid的虚拟索引。例如: + + ```sql + mogdb=> select * from hypopg_drop_index(329726); + hypopg_drop_index + ------------------- + t + (1 row) + ``` + + 使用函数hypopg_reset_index一次性清除所有创建的虚拟索引。例如: + + ```sql + mogdb=> select * from hypopg_reset_index(); + hypopg_reset_index + -------------------- + + (1 row) + ``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 执行EXPLAIN ANALYZE不会涉及虚拟索引功能。 +> - 创建的虚拟索引是数据库实例级别的,各个会话(session)之间可共享设置,关闭会话后虚拟索引仍可存在,但是重启数据库后将被清空。 +> - 本功能暂不支持视图、物化视图、列存表。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-3-workload-level-index-recommendation.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-3-workload-level-index-recommendation.md new file mode 100644 index 00000000..280d921f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/2-index-advisor-index-recommendation/2-3-workload-level-index-recommendation.md @@ -0,0 +1,117 @@ +--- +title: workload级别索引推荐 +summary: workload级别索引推荐 +author: Guo Huan +date: 2021-05-19 +--- + +# workload级别索引推荐 + +对于workload级别的索引推荐,用户可通过运行数据库外的脚本使用此功能,本功能将包含有多条DML语句的workload作为输入,最终生成一批可对整体workload的执行表现进行优化的索引。同时,本功能提供从日志中抽取业务数据SQL流水的功能。 + +
+ +## 前提条件 + +- 数据库状态正常、客户端能够正常连接。 + +- 当前执行用户下安装有gsql工具,该工具路径已被加入到PATH环境变量中。 + +- 若使用本功能提供的业务数据抽取功能,需提前将要收集的节点的GUC参数按如下设置: + + - log_min_duration_statement = 0 + + - log_statement= 'all' + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: + > + > 业务数据抽取完毕建议将上述GUC参数复原,否则容易导致日志文件膨胀。 + +
+ +## 业务数据抽取脚本使用步骤 + +1. 按前提条件中要求设置相关GUC参数。 + +2. 执行根据日志抽取SQL语句的功能,命令如下: + + ``` + gs_dbmind component extract_log [l LOG_DIRECTORY] [f OUTPUT_FILE] [p LOG_LINE_PREFIX] [-d DATABASE] [-U USERNAME][--start_time] [--sql_amount] [--statement] [--json] [--max_reserved_period] [--max_template_num] + ``` + + 其中的输入参数依次为: + + - LOG_DIRECTORY:pg_log的存放目录。 + - OUTPUT_PATH:输出SQL流水文件文件的保存路径,即抽取出的业务数据存放的文件路径。 + - LOG_LINE_PREFIX:指定每条日志信息的前缀格式。 + - DATABASE:(可选)数据库名称,不指定默认所有数据库。 + - USERNAME:(可选)用户名称,不指定默认所有用户。 + - start_time:(可选)日志收集的开始时间, 不指定默认所有文件。 + - sql_amount:(可选)收集SQL数量的最大值, 不指定默认收集所有SQL。 + - statement:(可选)表示收集pg_log日志中statement标识开头的SQL,不指定默认不收集。 + - json:(可选)指定收集日志的文件存储格式为SQL归一化后的json,不指定默认格式每条SQL占一行。 + - max_reserved_period:(可选)指定json模式下,增量收集日志中保留的模板的最大的更新时长,不指定默认都保留,单位/天。 + - max_template_num:(可选)指定json模式下保留的最大模板数量,不指定默认都保留。 + + 使用示例: + + ``` + gs_dbmind component extract_log $GAUSSLOG/pg_log/dn_6001 sql_log.txt '%m %c %d %p %a %x %n %e' -d postgres -U omm --start_time '2021-07-06 00:00:00' --statement + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 若指定-d/-U参数,日志打印每条日志信息的前缀格式需包含%d、%u,若需要抽取事务,必须指定%p,详见log_line_prefix参数。max_template_num参数设置建议不超5000条,避免workload索引推荐执行时间过长。 + +3. 将步骤1中设置的GUC参数还原为设置前的值。 + +
+ +## 索引推荐脚本使用步骤 + +1. 准备好包含有多条DML语句的文件作为输入的workload,文件中每条语句占据一行。用户可从数据库的离线日志中获得历史的业务语句。 + +2. 运行本功能,命令如下: + + ```python + gs_dbmind component index_advisor [p PORT] [d DATABASE] [f FILE] [--h HOST] [-U USERNAME] [-W PASSWORD][--schema SCHEMA] + [--max_index_num MAX_INDEX_NUM][--max_index_storage MAX_INDEX_STORAGE] [--multi_iter_mode] [--multi_node] [--json] [--driver] [--show_detail] + ``` + + 其中的输入参数依次为: + + - PORT:连接数据库的端口号。 + - DATABASE:连接数据库的名字。 + - FILE:包含workload语句的文件路径。 + - HOST:(可选)连接数据库的主机号。 + - USERNAME:(可选)连接数据库的用户名。 + - PASSWORD:(可选)连接数据库用户的密码。 + - SCHEMA:模式名称。 + - MAX_INDEX_NUM:(可选)最大的索引推荐数目。 + - MAX_INDEX_STORAGE:(可选)最大的索引集合空间大小。 + - multi_node:(可选)指定当前是否为分布式数据库实例。 + - multi_iter_mode:(可选)算法模式,可通过是否设置该参数来切换算法。 + - json:(可选)指定workload语句的文件路径格式为SQL归一化后的json,默认格式每条SQL占一行。 + - driver:(可选)指定是否使用python驱动器连接数据库,默认gsql连接。 + - show_detail:(可选)是否显示当前推荐索引集合的详细优化信息。 + + 例如: + + ```python + gs_dbmind component index_advisor 6001 postgres tpcc_log.txt --schema public --max_index_num 10 --multi_iter_mode + ``` + + 推荐结果为一批索引,以多个创建索引语句的格式显示在屏幕上,结果示例。 + + ```sql + create index ind0 on public.bmsql_stock(s_i_id,s_w_id); + create index ind1 on public.bmsql_customer(c_w_id,c_id,c_d_id); + create index ind2 on public.bmsql_order_line(ol_w_id,ol_o_id,ol_d_id); + create index ind3 on public.bmsql_item(i_id); + create index ind4 on public.bmsql_oorder(o_w_id,o_id,o_d_id); + create index ind5 on public.bmsql_new_order(no_w_id,no_d_id,no_o_id); + create index ind6 on public.bmsql_customer(c_w_id,c_d_id,c_last,c_first); + create index ind7 on public.bmsql_new_order(no_w_id); + create index ind8 on public.bmsql_oorder(o_w_id,o_c_id,o_d_id); + create index ind9 on public.bmsql_district(d_w_id); + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: multi_node参数需严格按照当前数据库架构进行指定,否则推荐结果不全,甚至导致无推荐结果。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-1-overview.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-1-overview.md new file mode 100644 index 00000000..f3c51acf --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-1-overview.md @@ -0,0 +1,10 @@ +--- +title: 概述 +summary: 概述 +author: Guo Huan +date: 2022-05-06 +--- + +# 概述 + +慢SQL一直是数据运维中的痛点问题,如何有效诊断慢SQL根因是当前一大难题,工具结合MogDB自身特点融合了现网DBA慢SQL诊断经验,该工具可以支持慢SQL根因15+,能同时按照可能性大小输出多个根因并提供针对性的建议。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-2-environment-deployment.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-2-environment-deployment.md new file mode 100644 index 00000000..6476f6ba --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-2-environment-deployment.md @@ -0,0 +1,11 @@ +--- +title: 环境部署 +summary: 环境部署 +author: Guo Huan +date: 2022-05-06 +--- + +# 环境部署 + +- 数据库运行正常。 +- 指标采集系统运行正常。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-3-usage-guide.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-3-usage-guide.md new file mode 100644 index 00000000..2d6cc606 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-3-usage-guide.md @@ -0,0 +1,34 @@ +--- +title: 使用指导 +summary: 使用指导 +author: Guo Huan +date: 2022-05-06 +--- + +# 使用指导 + +假设用户已经初始化配置文件目录confpath,则可以通过下述命令实现本特性的功能: + +- 仅启动慢SQL诊断功能(输出Top3根因),启动命令如下(更多用法参考对service子命令的说明): + + ``` + gs_dbmind service start -c confpath --only-run slow_query_diagnosis + ``` + +- 用户交互式慢SQL诊断,命令如下: + + ``` + gs_dbmind component slow_query_diagnosis show -c confpath --query SQL --start-time timestamps0 --end-time timestamps1 + ``` + +- 用户手动清理历史预测结果,命令如下: + + ``` + gs_dbmind component slow_query_diagnosis clean -c confpath --retention-days DAYS + ``` + +- 停止已启动的服务,命令如下: + + ``` + gs_dbmind service stop -c confpath + ``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-4-obtaining-help-information.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-4-obtaining-help-information.md new file mode 100644 index 00000000..379b2eb5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-4-obtaining-help-information.md @@ -0,0 +1,41 @@ +--- +title: 获取帮助 +summary: 获取帮助 +author: Guo Huan +date: 2022-05-06 +--- + +# 获取帮助 + +模块命令行说明: + +``` +gs_dbmind component slow_query_diagnosis --help +``` + +``` +usage: [-h] -c DIRECTORY [--query SLOW_QUERY] + [--start-time TIMESTAMP_IN_MICROSECONDS] + [--end-time TIMESTAMP_IN_MICROSECONDS] [--retention-days DAYS] + {show,clean} + +Slow Query Diagnosis: Analyse the root cause of slow query + +positional arguments: + {show,clean} choose a functionality to perform + +optional arguments: + -h, --help show this help message and exit + -c DIRECTORY, --conf DIRECTORY + set the directory of configuration files + --query SLOW_QUERY set a slow query you want to retrieve + --start-time TIMESTAMP_IN_MICROSECONDS + set the start time of a slow SQL diagnosis result to + be retrieved + --end-time TIMESTAMP_IN_MICROSECONDS + set the end time of a slow SQL diagnosis result to be + retrieved + --retention-days DAYS + clear historical diagnosis results and set the maximum + number of days to retain data +``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-5-command-reference.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-5-command-reference.md new file mode 100644 index 00000000..f0e0abc7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-5-command-reference.md @@ -0,0 +1,20 @@ +--- +title: 命令参考 +summary: 命令参考 +author: Guo Huan +date: 2022-05-06 +--- + +# 命令参考 + +**表 1** gs_dbmind component slow_query_diagnosis 命令行说明 + +| 参数 | 参数说明 | 取值范围 | +| :--------------- | :----------------------------- | :------------------------------------- | +| -h, --help | 帮助命令 | - | +| action | 动作参数 | - show:结果展示
- clean:清理结果 | +| -c,--conf | 配置目录 | - | +| --query | 慢SQL文本 | * | +| --start-time | 显示开始时间的时间戳,单位毫秒 | 非负整数 | +| --end-time | 显示结束时间的时间戳,单位毫秒 | 非负整数 | +| --retention-days | 清理天数级结果 | 非负实数 | \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-6-troubleshooting.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-6-troubleshooting.md new file mode 100644 index 00000000..623485a3 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/3-slow-query-diagnosis-root-cause-analysis-for-slow-sql-statements/3-6-troubleshooting.md @@ -0,0 +1,12 @@ +--- +title: 常见问题处理 +summary: 常见问题处理 +author: Guo Huan +date: 2022-05-06 +--- + +# 常见问题处理 + +- 如果用户对没有执行过的慢SQL执行交互式诊断命令,则无法给出诊断结果。 +- exporter指标采集功能没有启动时运行慢SQL诊断功能,此时功能无法正常运行。 +- 配置文件中的参数重新设置后,需要重新启动服务进程才能生效。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-1-overview.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-1-overview.md new file mode 100644 index 00000000..6ecdabbc --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-1-overview.md @@ -0,0 +1,10 @@ +--- +title: 概述 +summary: 概述 +author: Guo Huan +date: 2022-05-06 +--- + +# 概述 + +趋势预测功能模块主要实现基于历史时序数据预测未来时序变化趋势。该模块框架解耦,可以实现不同预测算法的灵活替换,并且该模块功能可以实现不同特征时序的算法自动选择,支持线性特征时序预测LR回归算法和非线性特征预测ARIMA算法。目前该模块可以覆盖线性时序、非线性时序和周期时序的准确预测。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-2-environment-deployment.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-2-environment-deployment.md new file mode 100644 index 00000000..c0388128 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-2-environment-deployment.md @@ -0,0 +1,10 @@ +--- +title: 环境部署 +summary: 环境部署 +author: Guo Huan +date: 2022-05-06 +--- + +# 环境部署 + +指标采集系统运行正常。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-3-usage-guide.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-3-usage-guide.md new file mode 100644 index 00000000..cb703244 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-3-usage-guide.md @@ -0,0 +1,34 @@ +--- +title: 使用指导 +summary: 使用指导 +author: Guo Huan +date: 2022-05-06 +--- + +# 使用指导 + +假设用户已经初始化配置文件目录confpath,则可以通过下述命令实现本特性的功能: + +- 仅启动趋势预测功能,启动命令如下(更多用法参考对service子命令的说明): + + ``` + gs_dbmind service start -c confpath --only-run forecast + ``` + +- 用户交互式趋势预测,查看timestamps0到timestamps1时间段内的预测结果,命令如下: + + ``` + gs_dbmind component forecast show -c confpath --start-time timestamps0 --end-time timestamps1 + ``` + +- 用户手动清理手动清理历史预测结果,命令如下: + + ``` + gs_dbmind component forecast clean -c confpath --retention-days DAYS + ``` + +- 停止已启动的服务,命令如下: + + ``` + gs_dbmind service stop -c confpath + ``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-4-obtaining-help-information.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-4-obtaining-help-information.md new file mode 100644 index 00000000..305836fa --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-4-obtaining-help-information.md @@ -0,0 +1,38 @@ +--- +title: 获取帮助 +summary: 获取帮助 +author: Guo Huan +date: 2022-05-06 +--- + +# 获取帮助 + +模块命令行说明: + +``` +gs_dbmind component forecast --help +``` + +``` +usage: [-h] -c DIRECTORY [--metric-name METRIC_NAME] [--host HOST] [--start-time TIMESTAMP_IN_MICROSECONDS] [--end-time TIMESTAMP_IN_MICROSECONDS] [--retention-days DAYS] + {show,clean} + +Workload Forecasting: Forecast monitoring metrics + +positional arguments: + {show,clean} choose a functionality to perform + +optional arguments: + -h, --help show this help message and exit + -c DIRECTORY, --conf DIRECTORY + set the directory of configuration files + --metric-name METRIC_NAME + set a metric name you want to retrieve + --host HOST set a host you want to retrieve + --start-time TIMESTAMP_IN_MICROSECONDS + set a start time of for retrieving + --end-time TIMESTAMP_IN_MICROSECONDS + set a end time of for retrieving + --retention-days DAYS + clear historical diagnosis results and set the maximum number of days to retain data +``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-5-command-reference.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-5-command-reference.md new file mode 100644 index 00000000..5c5c7604 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-5-command-reference.md @@ -0,0 +1,21 @@ +--- +title: 命令参考 +summary: 命令参考 +author: Guo Huan +date: 2022-05-06 +--- + +# 命令参考 + +**表 1** gs_dbmind component forecast 命令行说明 + +| 参数 | 参数说明 | 取值范围 | +| :--------------- | :----------------------------- | :------------------------------------- | +| -h, --help | 帮助命令 | - | +| action | 动作参数 | - show:结果展示
- clean:清理结果 | +| -c,--conf | 配置目录 | - | +| --metric-name | 指定显示指标名,用于过滤 | - | +| --host | 指定服务IP和端口号,用于过滤 | - | +| --start-time | 显示开始时间的时间戳,单位毫秒 | 非负实数 | +| --end-time | 显示结束时间的时间戳,单位毫秒 | 非负实数 | +| --retention-days | 保留结果天数 | 非负实数 | diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-6-troubleshooting.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-6-troubleshooting.md new file mode 100644 index 00000000..b1720652 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/4-forcast-trend-prediction/4-6-troubleshooting.md @@ -0,0 +1,11 @@ +--- +title: 常见问题处理 +summary: 常见问题处理 +author: Guo Huan +date: 2022-05-06 +--- + +# 常见问题处理 + +- 综合实际业务与模型预测效果考虑,趋势预测时长建议不要太短,建议大于3600秒(如果指标采集周期为15秒,则数据量为240个),否则预测效果会变差,并且数据量极小时,服务会异常,因此默认配置为3600秒 +- 配置文件中的参数重新设置后,需要重新启动服务进程才能生效。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-1-overview.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-1-overview.md new file mode 100644 index 00000000..cceab6a5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-1-overview.md @@ -0,0 +1,18 @@ +--- +title: 概述 +summary: 概述 +author: Guo Huan +date: 2021-05-19 +--- + +# 概述 + +SQLdiag是MogDB中SQL语句执行时长预测工具。现有的预测技术主要基于执行计划的预测方法,但这些预测方案仅适用于OLAP场景且可以获取执行计划的任务,对于OLTP或者HTAP这样的快速、简单查询是没有太多使用价值的。与上述方案不同,SQLdiag着眼于数据库的历史SQL语句,通过对历史SQL语句的执行表现进行总结归纳,将之再用于推断新的未知业务上。由于短时间内数据库SQL语句执行时长不会有太大的差距,SQLdiag可以从历史数据中检测出与已执行SQL语句相似的语句结果集,并基于SQL向量化技术通过SQL模板化和深度学习这两种方法来预测SQL语句执行时长。本工具有如下优点: + +1. 不需要SQL语句的执行计划,对数据库性能不会有任何的影响。 +2. 使用场景广泛,目前业内的很多算法局限性比较高,比如只适用于OLTP或者OLAP,而SQLdiag使用场景广泛。 +3. 该工具容易理解,只需要简单的操作,就可以训练出自己的预测模型。 + +SQLdiag是一个SQL语句执行时间预测工具,通过模板化方法或者深度学习方法,实现在不获取SQL语句执行计划的前提下,依据语句逻辑相似度与历史执行记录,预测SQL语句的执行时间并以此发现异常SQL。 + +本工具的典型应用场景是对一批即将上线的SQL语句进行透视,提前识别风险。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-2-usage-guide.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-2-usage-guide.md new file mode 100644 index 00000000..2e1562ad --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-2-usage-guide.md @@ -0,0 +1,96 @@ +--- +title: 使用指导 +summary: 使用指导 +author: Guo Huan +date: 2021-10-21 +--- + +# 使用指导 + +## 前提条件 + +- 需要保证用户提供训练数据。 +- 如果用户通过提供的工具收集训练数据,则需要启用WDR功能,涉及到的参数为track_stmt_stat_level和log_min_duration_statement,具体情况见下面小节。 +- 为保证预测准确率,用户提供的历史语句日志应尽可能全面并具有代表性。 + +## SQL流水采集方法 + +本工具需要用户提前准备数据,训练数据格式如下,每个样本通过换行符分隔: + +``` +SQL,EXECUTION_TIME +``` + +预测数据格式如下: + +``` +SQL +``` + +其中SQL表示**SQL语句的文本**,EXECUTION_TIME表示**SQL语句的执行时间**,样例数据见sample_data中的train.csv和predict.csv。 + +用户可以按照要求格式自己收集训练数据,工具也提供了脚本自动采集(load_sql_from_rd),该脚本基于WDR报告获取SQL信息,涉及到的参数有log_min_duration_statement和track_stmt_stat_level: + +- 其中log_min_duration_statement表示慢SQL阈值,如果为0则全量收集,时间单位为毫秒; +- track_stmt_stat_level表示信息捕获的级别,建议设置为track_stmt_stat_level='L0,L0' + +参数开启后,可能占用一定的系统资源,但一般不大。持续的高并发场景可能产生5%以内的损耗,数据库并发较低的场景,性能损耗可忽略。下述脚本存在于sqldiag根目录($**GAUSSHOME**/bin/components/sqldiag)中。 + +```bash +使用脚本获取训练集方式: +load_sql_from_wdr.py [-h] --port PORT --start_time START_TIME + --finish_time FINISH_TIME [--save_path SAVE_PATH] +例如: + python load_sql_from_wdr.py --start_time "2021-04-25 00:00:00" --finish_time "2021-04-26 14:00:00" --port 5432 --save_path ./data.csv +``` + +## 操作步骤 + +1. 提供历史日志以供模型训练 + +2. 进行训练与预测操作: + + ```bash + 基于模板法的训练与预测: + gs_dbmind component sqldiag [train, predict] -f FILE --model template --model-path template_model_path + 基于DNN的训练与预测: + gs_dbmind component sqldiag [train, predict] -f FILE --model dnn --model-path dnn_model_path + ``` + +## 使用方法示例 + +使用提供的测试数据进行模板化训练: + +```bash +gs_dbmind component sqldiag train -f ./sample_data/train.csv --model template --model-path ./template +``` + +使用提供的测试数据进行模板化预测: + +```bash +gs_dbmind component sqldiag predict -f ./sample_data/predict.csv --model template --model-path ./template --predicted-file ./result/t_result +``` + +使用提供的测试数据进行模板化模型更新: + +```bash +gs_dbmind component sqldiag finetune -f ./sample_data/train.csv --model template --model-path ./template +``` + +使用提供的测试数据进行DNN训练: + +```bash +gs_dbmind component sqldiag train -f ./sample_data/train.csv --model dnn --model-path ./dnn_model +``` + +使用提供的测试数据进行DNN预测: + +```bash +gs_dbmind component sqldiag predict -f ./sample_data/predict.csv --model dnn --model-path ./dnn_model --predicted-file +``` + +使用提供的测试数据进行DNN模型更新: + +```bash +gs_dbmind component sqldiag finetune -f ./sample_data/train.csv --model dnn --model-path ./dnn_model +``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-3-obtaining-help-information.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-3-obtaining-help-information.md new file mode 100644 index 00000000..d211ee54 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-3-obtaining-help-information.md @@ -0,0 +1,49 @@ +--- +title: 获取帮助 +summary: 获取帮助 +author: Guo Huan +date: 2021-05-19 +--- + +# 获取帮助 + +使用SQLdiag工具前,您可以通过以下指令获取帮助。 + +``` +gs_dbmind component sqldiag --help +``` + +显示如下帮助信息: + +``` +usage: [-h] [-f CSV_FILE] [--predicted-file PREDICTED_FILE] + [--model {template,dnn}] --model-path MODEL_PATH + [--config-file CONFIG_FILE] + {train,predict,finetune} + +SQLdiag integrated by MogDB. + +positional arguments: + {train,predict,finetune} + The training mode is to perform feature extraction and + model training based on historical SQL statements. The + prediction mode is to predict the execution time of a + new SQL statement through the trained model. + +optional arguments: + -h, --help show this help message and exit + -f CSV_FILE, --csv-file CSV_FILE + The data set for training or prediction. The file + format is CSV. If it is two columns, the format is + (SQL statement, duration time). If it is three + columns, the format is (timestamp of SQL statement + execution time, SQL statement, duration time). + --predicted-file PREDICTED_FILE + The file path to save the predicted result. + --model {template,dnn} + Choose the model model to use. + --model-path MODEL_PATH + The storage path of the model file, used to read or + save the model file. + --config-file CONFIG_FILE +``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-4-command-reference.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-4-command-reference.md new file mode 100644 index 00000000..4e0380d9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-4-command-reference.md @@ -0,0 +1,17 @@ +--- +title: 命令参考 +summary: 命令参考 +author: Guo Huan +date: 2021-05-19 +--- + +# 命令参考 + +**表 1** 命令行参数说明 + +| 参数 | 参数说明 | 取值范围 | +| :--------------- | :----------------- | :------------ | +| -f | 训练或预测文件位置 | - | +| --predicted-file | 预测结果存储位置 | - | +| --model | 模型选择 | template,dnn | +| --model-path | 训练模型存储位置 | - | diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-5-troubleshooting.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-5-troubleshooting.md new file mode 100644 index 00000000..bbbaf007 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai-sub-functions-of-the-dbmind/5-sqldiag-slow-sql-discovery/5-5-troubleshooting.md @@ -0,0 +1,11 @@ +--- +title: 常见问题处理 +summary: 常见问题处理 +author: Guo Huan +date: 2021-05-19 +--- + +# 常见问题处理 + +- 训练场景失败:请检查历史日志文件路径是否正确,且文件格式符合上文规定。 +- 预测场景失败:请检查模型路径是否正确。确保待预测负载文件格式正确。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai4db-autonomous-database-o&m.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai4db-autonomous-database-o&m.md new file mode 100644 index 00000000..cf18cc52 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/ai4db-autonomous-database-o&m.md @@ -0,0 +1,34 @@ +--- +title: AI4DB:数据库自治运维 +summary: AI4DB:数据库自治运维 +author: Guo Huan +date: 2022-05-06 +--- + +# AI4DB:数据库自治运维 + +如上文所述,AI4DB主要用于对数据库进行自治运维和管理,从而帮助数据库运维人员减少运维工作量。在实现上,DBMind的AI4DB框架具有监控和服务化的性质,同时也提供即时AI工具包,提供开箱即用的AI运维功能(如索引推荐)。AI4DB的监控平台以开源的Prometheus为主,DBMind提供监控数据生产者exporter, 可与Prometheus平台完成对接。DBMind的AI4DB服务架构如下图所示: + +**图 1** DBMind AI4DB服务架构 + +![DBMind-AI4DB服务架构](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/AI4DB-1.png) + +图中各关键组件说明: + +- DBMind Service:DBMind后台服务,可用于定期离线计算,包括慢SQL根因分析、时序预测等; +- Prometheus-server:Prometheus 监控指标存储的服务器; +- metadatabase:DBMind在离线计算结束后,将计算结果存储在此处,支持MogDB、SQLite等数据库; +- client:用户读取DBMind离线计算结果的客户端,目前仅实现命令行客户端;若采用MogDB等数据库存储计算DBMind计算结果,则用户可以自行配置Grafana等可视化工具对该结果进行可视化; +- openGauss-exporter:用户从MogDB数据库节点上采集监控指标,供DBMind服务进行计算; +- node-exporter:Prometheus官方提供的exporter, 可用于监控该节点的系统指标,如CPU和内存使用情况; +- reprocessing-exporter:用于对Prometheus采集到的指标进行二次加工处理,例如计算CPU使用率等。 + +## 环境配置 + +DBMind外置AI功能需要运行在Python 3.6版本及以上,需要的第三方依赖包记录在AI功能根目录(`$GAUSSHOME/bin/dbmind`)的`requirements.txt`文件中(包括`requirements-x86.txt`与`requirements-arrch64.txt`,用户可根据自己平台类型选择)中,可以通过`pip install`命令安装依赖,如: + +``` +pip install requirements-x86.txt +``` + +如果用户没有安装齐全所需的依赖,则当用户执行gs_dbmind命令时,会再次提醒用户安装第三方依赖。需要注意,该文件提供了DBMind所需的第三方依赖,若用户环境存在第三方包冲突等情况,可由用户根据实际情况进行处理。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/components-that-support-dbmind.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/components-that-support-dbmind.md new file mode 100644 index 00000000..fe118355 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/components-that-support-dbmind.md @@ -0,0 +1,10 @@ +--- +title: DBMind的支持组件 +summary: DBMind的支持组件 +author: Guo Huan +date: 2022-05-06 +--- + +# DBMind的支持组件 + +支持组件是指DBMind提供的用于支撑整个服务、解决方案能够部署和实施的模块。它们本身不是AI功能,却是整个服务体系中非常重要的一环,用于支撑整个自治运维解决方案的快速实施,如用于采集数据库指标的exporter等。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-command-reference.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-command-reference.md new file mode 100644 index 00000000..1f0471c7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-command-reference.md @@ -0,0 +1,136 @@ +--- +title: 命令参考 +summary: 命令参考 +author: Guo Huan +date: 2022-05-06 +--- + +# 命令参考 + +reprocessing-exporter的使用帮助详情: + +``` +gs_dbmind component reprocessing_exporter --help +usage: [-h] [--disable-https] [--ssl-keyfile SSL_KEYFILE] + [--ssl-certfile SSL_CERTFILE] + [--web.listen-address WEB.LISTEN_ADDRESS] + [--web.listen-port WEB.LISTEN_PORT] + [--collector.config COLLECTOR.CONFIG] [--log.filepath LOG.FILEPATH] + [--log.level {debug,info,warn,error,fatal}] [--version] + prometheus_host prometheus_port + +Reprocessing Exporter: A re-processing module for metrics stored in the +Prometheus server. + +positional arguments: + prometheus_host from which host to pull data + prometheus_port the port to connect to the Prometheus host + +optional arguments: + -h, --help show this help message and exit + --disable-https disable Https schema + --ssl-keyfile SSL_KEYFILE + set the path of ssl key file + --ssl-certfile SSL_CERTFILE + set the path of ssl certificate file + --web.listen-address WEB.LISTEN_ADDRESS + address on which to expose metrics and web interface + --web.listen-port WEB.LISTEN_PORT + listen port to expose metrics and web interface + --collector.config COLLECTOR.CONFIG + according to the content of the yaml file for metric + collection + --log.filepath LOG.FILEPATH + the path to log + --log.level {debug,info,warn,error,fatal} + only log messages with the given severity or above. + Valid levels: [debug, info, warn, error, fatal] + --version show program's version number and exit +``` + +**表 1** reprocessing-exporter的命令行参数详情表 + +| 参数 | 参数说明 | 取值范围 | +| :------------------- | :------------------------------------- | :------------------------------ | +| prometheus_host | Prometheus-server的IP地址 | - | +| prometheus_port | Prometheus-server的服务侦听端口号 | 1024-65535 | +| -h, --help | 帮助选项 | - | +| --disable-https | 禁用Https协议 | - | +| --ssl-keyfile | Https协议使用的证书私钥文件路径 | - | +| --ssl-certfile | Https协议使用的证书文件路径 | - | +| --web.listen-address | 该exporter服务的绑定IP | - | +| --web.listen-port | 该exporter服务的侦听端口 | 1024-65535 | +| --collector.config | 显性指定的待采集指标配置文件路径 | - | +| --log.filepath | 日志文件保存路径,默认保存在当前目录下 | - | +| --log.level | 日志文件的打印级别,默认为INFO级别 | debug, info, warn, error, fatal | +| --version | 显示版本信息 | - | + +openGauss-exporter的使用帮助详情: + +``` +gs_dbmind component opengauss_exporter --help +usage: [-h] --url URL [--config CONFIG] [--constant-labels CONSTANT_LABELS] + [--web.listen-address WEB.LISTEN_ADDRESS] + [--web.listen-port WEB.LISTEN_PORT] + [--web.telemetry-path WEB.TELEMETRY_PATH] [--disable-cache] + [--disable-settings-metrics] [--disable-statement-history-metrics] + [--disable-https] [--ssl-keyfile SSL_KEYFILE] + [--ssl-certfile SSL_CERTFILE] [--parallel PARALLEL] + [--log.filepath LOG.FILEPATH] + [--log.level {debug,info,warn,error,fatal}] [--version] + +openGauss Exporter (DBMind): Monitoring for MogDB. + +optional arguments: + -h, --help show this help message and exit + --url URL MogDB database target url. + --config CONFIG path to config dir or file. + --constant-labels CONSTANT_LABELS + a list of label=value separated by comma(,). + --web.listen-address WEB.LISTEN_ADDRESS + address on which to expose metrics and web interface + --web.listen-port WEB.LISTEN_PORT + listen port to expose metrics and web interface + --web.telemetry-path WEB.TELEMETRY_PATH + path under which to expose metrics. + --disable-cache force not using cache. + --disable-settings-metrics + not collect pg_settings.yml metrics. + --disable-statement-history-metrics + not collect statement-history metrics (including slow + queries). + --disable-https disable Https schema + --ssl-keyfile SSL_KEYFILE + set the path of ssl key file + --ssl-certfile SSL_CERTFILE + set the path of ssl certificate file + --parallel PARALLEL not collect pg_settings.yml metrics. + --log.filepath LOG.FILEPATH + the path to log + --log.level {debug,info,warn,error,fatal} + only log messages with the given severity or above. + Valid levels: [debug, info, warn, error, fatal] + --version show program's version number and exit +``` + +**表 2** openGauss-exporter的命令行参数详情表 + +| 参数 | 参数说明 | 取值范围 | +| :---------------------------------- | :----------------------------------------------------------- | :------------------------------ | +| --url | MogDB server的连接地址,例如 postgres://user:pwd@host:port/dbname | - | +| --constant-labels | 常量标签,将采集到的指标项中强行添加该标签列表 | 1024-65535 | +| -h, --help | 帮助选项 | - | +| --disable-https | 禁用Https协议 | - | +| --ssl-keyfile | Https协议使用的证书私钥文件路径 | - | +| --ssl-certfile | Https协议使用的证书文件路径 | - | +| --web.listen-address | 该exporter服务的绑定IP | - | +| --web.listen-port | 该exporter服务的侦听端口 | 1024-65535 | +| --web.telemetry-path | 该exporter采集指标的URI地址,默认为 /metrics | - | +| --config | 显性指定的待采集指标配置文件路径 | - | +| --log.filepath | 日志文件保存路径,默认保存在当前目录下 | - | +| --log.level | 日志文件的打印级别,默认为INFO级别 | debug, info, warn, error, fatal | +| --version | 显示版本信息 | - | +| --disable-cache | 禁止使用缓存 | - | +| --disable-settings-metrics | 禁止采集pg_settings表的值 | - | +| --disable-statement-history-metrics | 禁止收集statement_history表中的慢SQL信息 | - | +| --parallel | 连接到MogDB的数据库连接池的大小 | 正整数 | \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-environment-deployment.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-environment-deployment.md new file mode 100644 index 00000000..64cb99e2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-environment-deployment.md @@ -0,0 +1,33 @@ +--- +title: 环境部署 +summary: 环境部署 +author: Guo Huan +date: 2022-05-06 +--- + +# 环境部署 + +1. 通过命令行参数启动对应的exporter进程,同时在本地机器创建侦听端口号。 + +2. 在Promethues的服务器端修改配置文件prometheus.yml,将启动的exporter信息添加进去,例如: + + ``` + scrape_configs: + ... + - job_name: 'opengauss_exporter' + static_configs: + - targets: ['127.0.0.1:9187'] + ... + ``` + +其中,提供的exporter组件默认采用Https通信协议,因此需要用户默认提供ssl证书和秘钥文件,并通过--ssl-keyfile以及--ssl-certfile提供。若用户不希望使用Https协议,则可以通过--disable-https选项禁用该模式。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> 由于MogDB默认模式下的通信加密协议与PostgreSQL不兼容,故导致通过PyPI源安装的基于PostgreSQL编译的Python驱动psycopg2-binary默认无法连接至MogDB数据库。 +> 因此,需要用户自行编译psycopg2或修改GUC参数进行适配。也可通过openGauss官方网站下载基于openGauss编译的psycopg2(官方网站仅提供部分Python版本的编译包,一般为Python3.6版本,需要用户鉴别)。 +> +> - 官方openGauss Python驱动下载地址为: +> [https://opengauss.org/zh/download.html](https://opengauss.org/zh/download.html) +> - 关于Python驱动的适配问题,可参考openGauss官方操作指南: +> [https://mp.weixin.qq.com/s/2TobUQKtw0N9sBpMZJr6zw](https://mp.weixin.qq.com/s/2TobUQKtw0N9sBpMZJr6zw) diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-obtaining-help-information.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-obtaining-help-information.md new file mode 100644 index 00000000..4eaa1f7b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-obtaining-help-information.md @@ -0,0 +1,15 @@ +--- +title: 获取帮助 +summary: 获取帮助 +author: Guo Huan +date: 2022-05-06 +--- + +# 获取帮助 + +用户可以通过--help命令获取帮助信息,例如: + +``` +gs_dbmind component opengauss_exporter --help +gs_dbmind component reprocessing_exporter --help +``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-overview.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-overview.md new file mode 100644 index 00000000..8b5a4928 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-overview.md @@ -0,0 +1,12 @@ +--- +title: 概述 +summary: 概述 +author: Guo Huan +date: 2022-05-06 +--- + +# 概述 + +Prometheus是业内非常流行的开源监控系统,同时本身也是一款时序数据库。Prometheus的采集端称之为exporter,用来收集被监控模块的指标项。为了与Prometheus平台完成对接,AI工具分别实现了两款exporter,分别是用来采集数据库指标的openGauss-exporter,以及对采集到的指标进行二次加工的reprocessing-exporter。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: Prometheus 和exporter是业内流行的监控和采集平台,部署在内网环境中,不对外部暴露接口,仅供内部监控平台使用。因此,为了增强该平台的安全性,一般需要用户或运维人员配置防火墙等,以便隔离外部访问,从而增强监控平台的安全性。 Prometheus平台在默认情况下,采用Http协议、并且没有任何安全访问限制。这是因为,该平台一般部署在内网环境中,攻击风险可控。如果用户希望提高安全性,可自行修改Prometheus的TLS配置选项,但仍不建议对外部直接暴露访问接口。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-troubleshooting.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-troubleshooting.md new file mode 100644 index 00000000..8962f5c9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-troubleshooting.md @@ -0,0 +1,16 @@ +--- +title: 常见问题处理 +summary: 常见问题处理 +author: Guo Huan +date: 2022-05-06 +--- + +# 常见问题处理 + +1. 提示需要用户提供--ssl-keyfile与--ssl-certfile选项: + + 上述exporter默认采用Https模式通信,因此需要用户指定证书及其私钥文件的路径。相反,如果用户只想采用Http模式,则需要显性给定--disable-https选项,从而禁用Https协议。 + +2. 提示用户需要输入PEM密码(Enter PEM pass phrase): + + 如果用户采用Https模式,并给定了证书及其秘钥文件的路径,且该秘钥文件是经过加密的,则需要用户输入该加密私钥证书文件的密码。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-usage-guide.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-usage-guide.md new file mode 100644 index 00000000..80c98783 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/components-that-support-dbmind/prometheus-exporter/prometheus-exporter-usage-guide.md @@ -0,0 +1,62 @@ +--- +title: 使用指导 +summary: 使用指导 +author: Guo Huan +date: 2022-05-06 +--- + +# 使用指导 + +用户可通过gs_dbmind命令启动对应的exporter。下面为用户演示一个完整的Prometheus监控平台的搭建过程。 + +1. 部署openGauss-exporter:启动openGauss-exporter,采用默认侦听端口号9187,侦听地址为192.168.1.100,不采用https协议,则命令可以为: + + ```bash + gs_dbmind component opengauss_exporter --url postgresql://user:password@ip:port/dbname --web.listen-address 192.168.1.100 --disable-https + ``` + +2. 部署reprocessing-exporter:启动reprocessing-exporter,采用默认侦听端口号8181,侦听地址为192.168.1.101,Prometheus-server IP与端口号为192.168.1.100:9090,采用https协议,则命令可以为: + + ```bash + gs_dbmind component reprocessing_exporter 192.168.1.100 9090 --web.listen-address 192.168.1.101 --ssl-keyfile server.key --ssl-certfile server.crt + ``` + +3. 部署node-exporter:一般地,对于Prometheus监控平台都需要部署node-exporter用于监控Linux操作系统,后文提到的部分AI功能也需要依赖node-exporter采集Linux系统指标,故也需要用户来部署;只不过,该node-exporter为Prometheus自带组件,需要用户自行下载安装,下载地址为[https://prometheus.io/download/#node_exporter](https://prometheus.io/download/#node_exporter),使用方法详见:[https://prometheus.io/docs/guides/node-exporter/#installing-and-running-the-node-exporter](https://prometheus.io/docs/guides/node-exporter/#installing-and-running-the-node-exporter)。用户可解压压缩包后直接运行该node-exporter进程,其默认端口号为9100,启动命令行为: + + ``` + ./node_exporter + ``` + +4. 配置Prometheus-server,修改配置文件prometheus.yml,添加下述内容: + + ```yaml + scrape_configs: + ... + - job_name: 'opengauss_exporter' + static_configs: + - targets: ['192.168.1.100:9187'] + - job_name: 'reprocessing_exporter' + scheme: https + tls_config: + ca_file: xxx.crt + static_configs: + - targets: ['127.0.0.1:8181'] + - job_name: 'node_exporter' + static_configs: + - targets: ['127.0.0.1:9100'] + ... + ``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** +> +> - openGauss-exporter中连接数据库的用户需要monitor admin或以上权限,否则会出现部分指标无法采集的情况。 +> - openGauss-exporter会从dbe_perf.statement_history中抽样慢SQL信息,dbe_perf.statement_history视图慢SQL记录与GUC参数log_min_duration_statement和track_stmnt_stat_level相关,其中log_min_duration_statement是慢SQL阈值,单位毫秒,具体值由用户设置;track_stmnt_stat_level是SQL记录级别,默认为'OFF,L0',即只记录慢SQL信息,级别为L0,用户在详细了解参数意义与作用情况下谨慎修改。 +> - openGauss-exporter采集数据库相关信息,主要包括部分系统表和视图中的数据(具体参见代码中opengauss_exporter中的配置文件),node-exporter采集系统指标信息,主要与系统磁盘、CPU等相关,reprocessing_exporter基于prometheus-server中的某些指标(具体参见代码中reprocessing_exporter中的配置文件)进行二次加工,最终提供加工后的数据供用户使用。 +> - prometheus-server在拉取exporter数据时有超时机制,超时时间由scrape_timeout(默认10s)控制,因此当exporter采集数据量较大时,用户可根据实际情况增大scrape_timeout以防止超时报错,另外需要注意的是scrape_interval(采集间隔)不能比scrape_timeout小,否则会出现异常。 +> - 如果数据库时区设置和系统不相同,可能会出现时间相关指标时间与系统时间不一致的情况,因此需要将用户时区与系统保持同步。 +> - 当使用https通信时,工具会检测证书与密钥文件权限以及证书有效期,如果文件权限大于600则会出现报警,证书有效期小于90天会出现报警。 +> - 当存在指标重复采集时,openGauss-exporter会出现异常,异常信息会打印到日志中。 +> - openGauss-exporter的--config、--disable-settings-metrics、--disable-statement-history-metrics三个参数需要注意,其存在以下几种情况: +> 1. 用户不指定其中任何参数,则工具会同时对yamls目录下的三个配置文件中的指标进行采集。 +> 2. 用户显式指定--config,则工具不会采集yamls目录下default.yml中的指标,而会采集用户指定配置文件中的指标,同时pg_settings.yml和statements.yml正常采集,此时用户需要注意指定的配置文件中的指标和pg_settings.yml、statements.yml中的指标不能存在重复采集的现象。 +> 3. 用户显式指定--disable-settings-metrics,则工具不会采集yamls目录下pg_settings.yml中的指标,用户显式指定--disable-statement-history-metrics,则工具不会采集yamls目录下statements.yml(慢SQL相关)中的指标。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/1-service.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/1-service.md new file mode 100644 index 00000000..f3832d05 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/1-service.md @@ -0,0 +1,148 @@ +--- +title: service子命令 +summary: service子命令 +author: Guo Huan +date: 2022-05-06 +--- + +# service子命令 + +该子命令可用于对配置目录进行初始化,同时也可以实现启动和停止后台任务。 + +## 配置目录初始化 + +用户可通过`gs_dbmind service setup`子命令进行配置目录的初始化。该配置文件中可包括DBMind的配置文件、日志等内容。该目录中的部分文件说明: + +- dbmind.conf:DBMind的参数配置文件,用户可通过`gs_dbmind set`命令进行修改,也可通过文本编辑器进行手动修改。 +- dynamic_config.db:DBMind服务保存在本地节点的元信息,主要包括算法的超参数、监控阈值等;该文件为DBMind服务元信息,不可由用户直接配置。 +- metric_map.conf:监控指标映射表,可用于适配到不同采集平台中。例如,在DBMind中,监控到的系统cpu使用率名为os_cpu_usage,而用户自行实现的指标采集工具将cpu使用率命名为my_cpu_usage_rate。在该种情况下,如果想要DBMind代表cpu使用率的指标名为my_cpu_usage_rate,则需要修改该配置选项。即添加“os_cpu_usage = my_cpu_usage_rate”配置项进行映射。对于普通用户,建议直接使用DBMind配套的采集组件和方案,则不涉及修改该配置文件。 +- logs: 该目录中用于存储DBMind服务产生的日志。 + +用户可通过两种方式进行配置目录的初始化,一种为交互式,另一种为非交互式。例如,待初始化的配置目录名为**confpath**, 则分别通过下述方法进行配置: + +**交互式模式** + +``` +gs_dbmind service setup -c confpath --interactive +``` + +执行完毕上述命令后,用户可通过命令行终端对配置项进行交互式配置。 + +**非交互式模式** + +非交互式模式总共分为三个步骤,即启动配置,修改配置项,初始化配置。其中第二个步骤需要用户通过文本编辑器手动编辑配置文件。具体步骤如下: + +1. 启动配置,执行下述命令: + + ``` + gs_dbmind service setup -c confpath + ``` + +2. 执行完上述命令后,会在confpath目录下生成dbmind.conf配置文件,用户需要利用文本编辑器进行手动修改。需要修改的配置部分为“指标数据源数据库信息区【TSDB】”、“预测结果存储数据库信息区【METADATABASE】”和“自监控参数配置区【SELF-MONITORING】”相关参数的说明如下: + + ``` + [TSDB] # 时序数据库相关信息,即指标数据源信息 + name = prometheus # 时序数据库类型. 当前仅支持选择'prometheus'. + host = # 时序数据库IP地址. + port = # 时序数据库端口号. + + [METADATABASE] # 元数据库相关信息,及预测结果存储方式 + dbtype = # 元数据库类型. 可选择: sqlite, mogdb, postgresql。若该配置项名为mogdb, 需关注Python驱动事宜,可参考下文中关于Python驱动的提示。 + host = # 元数据库地址. + port = # 元数据库端口号. + username = # 元数据库用户信息. + password = # 元数据库密码,将会被加密存储 + database = # 元数据库库名. 如果选择的数据库类型为SQLite, 则无需填写上述配置项,仅需填写此处。DBMind会根据database配置项的内容,在配置目录中生成对应文件名的SQLite数据库文件。 + + [SELF-MONITORING] # 自监控参数配置 + detection_interval = 600 # 单位秒. 对mogdb进行健康检查的时间间隔(仅慢SQL根因诊断使用). + last_detection_time = 600 # 单位秒. 用于健康检查的监控数据长度(仅慢SQL根因诊断使用). + forecasting_future_time = 3600 # 单位秒,时序预测的长度(供时序预测特性使用),同时也是预测功能调度周期 + # 待时序预测进行预测的关键指标项(仅供时序预测特性使用) + golden_kpi = os_cpu_usage, os_mem_usage, gaussdb_qps_by_instance + + [LOG] # 日志相关信息 + maxbytes = 10485760 # 默认值为 10Mb, 单个日志文件的最大大小.如果 maxbytes 为零,则文件无限增长(建议该值不要设置太小,默认即可). + backupcount = 1 # 日志文件最大数量. + level = INFO # 日志级别,也可配置为 DEBUG, INFO, WARNING, ERROR模式。 + ``` + +3. 待用户手动修改完上述参数后,需要执行下述命令进行配置项的初始化。在该阶段中,DBMind会初步检查配置项的正确性、加密配置项中出现的明文密码、同时初始化用于存储结果数据的元数据库。 + + ``` + gs_dbmind service setup --initialize -c confpath + ``` + +4. 完成配置目录初始化过程,可基于该配置目录启动DBMind后台服务。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> 1. 配置文件注释信息用于在交互模式下对用户进行提示,有特殊含义不要手动修改或删除; +> 2. 需要确保配置项的值与注释信息之间通过空格符分割,否则系统会将注释信息识别为配置项的值; +> 3. 配置项中的特殊字符,如果需要转移,则通过转义符“百分号”(%)来转义,例如,用户配置的密码为 “password%”, 则应通过“百分号”进行转义,即 “password%%“。 + +## 启动服务 + +当用户完成配置目录的初始化后,可基于此配置目录启动DBMind后台服务。例如配置目录为confpath,则启动命令如下: + +``` +gs_dbmind service start -c confpath +``` + +当执行上述命令后,会提示服务已启动。在未指定任何附加参数时,该命令默认会启动所有的后台任务。如果用户只想启动某一个后台任务,需要添加参数--only-run。例如,用户只想启动慢SQL根因分析服务,则为: + +``` +gs_dbmind service start -c confpath --only-run slow_query_diagnosis +``` + +## 关闭服务 + +关闭服务与启动服务类似,其命令行结构更加简单,只需指定配置目录的地址即可。例如配置目录为confpath,则为: + +``` +gs_dbmind service stop -c confpath +``` + +DBMind服务会在后台执行完正在运行的任务后自行退出。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** +> +> - [METADATABASE]中的元数据库用户需要具有在该数据库下的创表和数据插入更新权限,否则工具执行会出现异常。 +> - 当前不支持同一配置文件下分开启动多个服务。 +> - 工具提供了requirement.txt文件,用户可以通过该文件安装所需的第三方依赖。 + +## 命令参考 + +用户可以通过--help选项获得该模式的帮助信息,例如: + +``` +gs_dbmind service --help +``` + +``` +usage: service [-h] -c DIRECTORY [--only-run {slow_query_diagnosis,forecast}] [--interactive | --initialize] {setup,start,stop} + +positional arguments: + {setup,start,stop} + perform an action for service + +optional arguments: + -h, --help show this help message and exit + -c DIRECTORY, --conf DIRECTORY + set the directory of configuration files + --only-run {slow_query_diagnosis,forecast} + explicitly set a certain task running in the backend + --interactive configure and initialize with interactive mode + --initialize initialize and check configurations after configuring. +``` + +**表 1** gs_dbmind service 子命令说明 + +| 参数 | 参数说明 | 取值范围 | +| :------------ | :----------------- | :----------------------------------------------------------- | +| action | 动作参数 | - setup:初始化配置目录。
- start:服务启动。
- stop:服务停止。 | +| -c,--conf | 配置文件目录地址 | - | +| --initialize | 配置参数初始化 | - | +| --interactive | 交互式输入配置参数 | - | +| --only-run | 选择只运行的模块 | - forecast:预测模块。
- slow_query_diagnosis:慢SQL根因分析模块。 | +| -h, --help | 帮助命令 | - | diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/2-component.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/2-component.md new file mode 100644 index 00000000..29f8bea9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/2-component.md @@ -0,0 +1,37 @@ +--- +title: component子命令 +summary: component子命令 +author: Guo Huan +date: 2022-05-06 +--- + +# component子命令 + +该子命令可以用于启动DBMind的组件,包括可用于监控指标的exporter,以及AI功能等。该命令可以将用户通过命令行传入的命令转发给对应的子组件,故不同的子组件命令需参考其功能的对应说明,详见后文各个子组件对应章节,此处不再赘述。 + +## 命令参考 + +用户可以通过--help选项获得该模式的帮助信息,例如: + +``` +gs_dbmind component --help +``` + +``` +usage: component [-h] COMPONENT_NAME ... + +positional arguments: + COMPONENT_NAME choice a component to start. ['extract_log', 'forecast', 'index_advisor', 'opengauss_exporter', 'reprocessing_exporter', 'slow_query_diagnosis', 'sqldiag', 'xtuner'] + ARGS arguments for the component to start + +optional arguments: + -h, --help show this help message and exit +``` + +**表 1** gs_dbmind component 子命令说明 + +| 参数 | 参数说明 | 取值范围 | +| :------------- | :----------- | :----------------------------------------------------------- | +| COMPONENT_NAME | 子组件名 | extract_log, forecast, index_advisor, opengauss_exporter, reprocessing_exporter, slow_query_diagnosis, sqldiag, xtuner | +| ARGS | 子组件的参数 | 参考子组件的命令说明 | +| -h, --help | 帮助命令 | - | \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/3-set.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/3-set.md new file mode 100644 index 00000000..9e413a73 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/3-set.md @@ -0,0 +1,54 @@ +--- +title: set子命令 +summary: set子命令 +author: Guo Huan +date: 2022-05-06 +--- + +# set子命令 + +该命令用于修改配置文件dbmind.conf中的参数值,与用户手动修改配置文件dbmind.conf一般无差异。例如修改配置目录confpath中的配置文件dbmind.conf中TSDB配置部分,host参数的值,并将其设置为127.0.0.1。则可通过下述命令实现: + +``` +gs_dbmind set TSDB host 127.0.0.1 -c confpath +``` + +在修改上述普通参数时,与手动修改配置文件dbmind.conf无差异。但是,当用户想要修改密码项时,则必须通过该命令才可以实现修改,否则通过用户手动修改的配置文件无法实现对明文密码的加密,例如: + +``` +gs_dbmind set METADATABASE password xxxxxx -c confpath +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 该命令对于字符串是大小写敏感的,如果输错则可能出现执行过程错误。 + +## 命令参考 + +用户可以通过--help选项获得该模式的帮助信息,例如: + +``` +gs_dbmind set --help +``` + +``` +usage: set [-h] -c DIRECTORY section option target + +positional arguments: + section which section (case sensitive) to set + option which option to set + target the parameter target to set + +optional arguments: + -h, --help show this help message and exit + -c DIRECTORY, --conf DIRECTORY + set the directory of configuration files +``` + +**表 1** 模块命令行参数说明:python dbmind/ set xxx + +| 参数 | 参数说明 | 取值范围 | +| :--------- | :------------------- | :------- | +| -h, --help | 帮助命令 | - | +| -c,--conf | 配置文件目录confpath | - | +| section | 设置区 | - | +| option | 设置项 | - | +| target | 设置值 | - | diff --git a/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/dbmind-mode.md b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/dbmind-mode.md new file mode 100644 index 00000000..d08aa4e8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/ai4db/dbmind-mode/dbmind-mode.md @@ -0,0 +1,47 @@ +--- +title: DBMind模式说明 +summary: DBMind模式说明 +author: Guo Huan +date: 2022-05-06 +--- + +# DBMind模式说明 + +用户可通过gs_dbmind命令调用AI4DB的全部功能,该命令可实现下列基本功能: + +- 服务功能:service子命令,包括创建并初始化配置目录、启动后台服务、关闭后台服务等; +- 调用组件:component子命令,AI4DB功能(如索引推荐、参数调优等)可通过该模式进行即时调用; +- 设置参数:set子命令,通过该命令,可以一键修改配置目录中的配置文件值;当然,用户也可以通过文本编辑器进行手动修改; + +用户可以通过--help选项获得上述模式的帮助信息,例如: + +``` +gs_dbmind --help +``` + +``` +usage: [-h] [--version] {service,set,component} ... + +MogDB DBMind: An autonomous platform for MogDB + +optional arguments: + -h, --help show this help message and exit + --version show program's version number and exit + +available subcommands: + {service,set,component} + type ' -h' for help on a specific subcommand + service send a command to DBMind to change the status of the service + set set a parameter + component pass command line arguments to each sub-component. +``` + +**表 1** gs_dbmind 选项基本说明 + +| 参数 | 参数说明 | 取值范围 | +| :--------- | :------------------- | :------- | +| -h, --help | 帮助命令 | - | +| --version | 版本号 | - | +| service | 服务功能相关的子命令 | - | +| component | 调用组件的子命令 | - | +| set | 修改配置文件的子命令 | - | \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/AI-features/db4ai/db4ai.md b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/db4ai.md new file mode 100644 index 00000000..8c17535e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/db4ai.md @@ -0,0 +1,10 @@ +--- +title: DB4AI:数据库驱动AI +summary: DB4AI:数据库驱动AI +author: Guo Huan +date: 2022-05-06 +--- + +# DB4AI:数据库驱动AI + +DB4AI是指利用数据库的能力驱动AI任务,实现数据存储、技术栈的同构。通过在数据库内集成AI算法,令MogDB具备数据库原生AI计算引擎、模型管理、AI算子、AI原生执行计划的能力,为用户提供普惠AI技术。不同于传统的AI建模流程,DB4AI“一站式”建模可以解决数据在各平台的反复流转问题,同时简化开发流程,并可通过数据库规划出最优执行路径,让开发者更专注于具体业务和模型的调优上,具备同类产品不具备的易用性与性能优势。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/db4ai-snapshots-for-data-version-management.md b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/db4ai-snapshots-for-data-version-management.md new file mode 100644 index 00000000..dae34662 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/db4ai-snapshots-for-data-version-management.md @@ -0,0 +1,266 @@ +--- +title: DB4AI-Snapshots数据版本管理 +summary: DB4AI-Snapshots数据版本管理 +author: Guo Huan +date: 2022-05-06 +--- + +# DB4AI-Snapshots数据版本管理 + +DB4AI-Snapshots是DB4AI模块用于管理数据集版本的功能。通过DB4ai-Snapshots组件,开发者可以简单、快速地进行特征筛选、类型转换等数据预处理操作,同时还可以像git一样对训练数据集进行版本控制。数据表快照创建成功后可以像视图一样进行使用,但是一经发布后,数据表快照便固化为不可变的静态数据,如需修改该数据表快照的内容,需要创建一个版本号不同的新数据表快照。 + +## DB4AI-Snapshots的生命周期 + +DB4AI-Snapshots的状态包括published、archived以及purged。其中,published可以用于标记该DB4AI-Snapshots 已经发布,可以进行使用。archived表示当前 DB4AI-Snapshots 处于“存档期”,一般不进行新模型的训练,而是利用旧数据对新的模型进行验证。purged则是该DB4AI-Snapshots 已经被删除的状态,在数据库系统中无法再检索到。 + +需要注意的是快照管理功能是为了给用户提供统一的训练数据,不同团队成员可以使用给定的训练数据来重新训练机器学习模型,方便用户间协同。为此**私有用户**和**三权分立**状态(enableSeparationOfDuty=ON)等涉及不支持用户数据转写等情况将不支持Snapshot特性。 + +用户可以通过“CREATE SNAPSHOT”语句创建数据表快照,创建好的快照默认即为published状态。可以采用两种模式创建数据表快照,即为MSS以及CSS模式,它们可以通过GUC参数db4ai_snapshot_mode进行配置。对于MSS模式,它是采用物化算法进行实现的,存储了原始数据集的数据实体;CSS则是基于相对计算算法实现的,存储的是数据的增量信息。数据表快照的元信息存储在DB4AI的系统目录中。可以通过db4ai.snapshot 系统表查看到。 + +可以通过“ARCHIVE SNAPSHOT”语句将某一个数据表快照标记为archived状态,可以通过“PUBLISH SNAPSHOT”语句将其再度标记为published状态。标记数据表快照的状态,是为了帮助数据科学家进行团队合作使用的。 + +当一个数据表快照已经丧失存在价值时,可以通过“PURGE SNAPSHOT”语句删除它,以便永久删除其数据并恢复存储空间。 + +## DB4AI-Snapshots使用指导 + +1. 创建表以及插入表数据。 + + 数据库内存在已有的数据表,可根据该已有的数据表创建对应的数据表快照。为了后续演示,在此处新建一个名为 t1 的数据表,并向其中插入测试数据。 + + ```sql + create table t1 (id int, name varchar); + insert into t1 values (1, 'zhangsan'); + insert into t1 values (2, 'lisi'); + insert into t1 values (3, 'wangwu'); + insert into t1 values (4, 'lisa'); + insert into t1 values (5, 'jack'); + ``` + + 通过SQL语句,查询搭配数据表内容。 + + ```sql + SELECT * FROM t1; + id | name + ----+---------- + 1 | zhangsan + 2 | lisi + 3 | wangwu + 4 | lisa + 5 | jack + (5 rows) + ``` + +2. 使用DB4AI-Snapshots。 + + - 创建DB4AI-Snapshots + + - 示例1:CREATE SNAPSHOT…AS + + 示例如下,其中,默认版本分隔符为 “@”, 默认子版本分割符为 “.”,该分割符可以分别通过GUC参数db4ai_snapshot_version_delimiter以及db4ai_snapshot_version_separator进行设置。 + + ```sql + create snapshot s1@1.0 comment is 'first version' as select * from t1; + schema | name + --------+-------- + public | s1@1.0 + (1 row) + ``` + + 上述结果提示已经创建了数据表 s1的快照,版本号为 1.0。创建好后的数据表快照可以像使用一般视图一样进行查询,但不支持通过“INSERT INTO”语句进行更新。例如下面几种语句都可以查询到数据表快照s1的对应版本 1.0的内容: + + ```sql + SELECT * FROM s1@1.0; + SELECT * FROM public.s1@1.0; + SELECT * FROM public . s1 @ 1.0; + id | name + ----+---------- + 1 | zhangsan + 2 | lisi + 3 | wangwu + 4 | lisa + 5 | jack + (5 rows) + ``` + + 可以通过下列SQL语句修改数据表t1的内容: + + ```sql + UPDATE t1 SET name = 'tom' where id = 4; + insert into t1 values (6, 'john'); + insert into t1 values (7, 'tim'); + ``` + + 再检索数据表t1的内容时,发现虽然数据表t1的内容已经发生变化,但是数据表快照 s1@1.0 版本的查询结果并未发生变化。由于数据表t1的数据已经发生了改变,如果将当前数据表的内容作为版本2.0,则可创建快照**s1@2.0**,创建的SQL语句如下: + + ```sql + create snapshot s1@2.0 as select * from t1; + ``` + + 通过上述例子,我们可以发现,数据表快照可以固化数据表的内容,避免中途对数据的改动造成机器学习模型训练时的不稳定,同时可以避免多用户同时访问、修改同一个表时造成的锁冲突。 + + - 示例2:CREATE SNAPSHOT…FROM + + SQL语句可以对一个已经创建好的数据表快照进行继承,利用在此基础上进行的数据修改产生一个新的数据表快照。例如: + + ```sql + create snapshot s1@3.0 from @1.0 comment is 'inherits from @1.0' using (INSERT VALUES(6, 'john'), (7, 'tim'); DELETE WHERE id = 1); + schema | name + --------+-------- + public | s1@3.0 + (1 row) + ``` + + 其中,“@”为数据表快照的版本分隔符,from子句后加上已存在的数据表快照,用法为“@”+版本号,USING关键字后加入可选的几个操作关键字(INSERT …/UPDATE …/DELETE …/ALTER …),其中 “INSERT INTO”以及“DELETE FROM”语句中的“INTO”、“FROM”等与数据表快照名字相关联的子句可以省略,具体可以参考[AI特性函数](../../../reference-guide/functions-and-operators/28-ai-feature-functions.md)。 + + 示例中,基于前述 `s1@1.0` 快照,插入2条数据,删除1条新的数据,新生成的快照 `s1@3.0`,检索该 `s1@3.0`: + + ```sql + SELECT * FROM s1@3.0; + id | name + ----+---------- + 2 | lisi + 3 | wangwu + 4 | lisa + 5 | jack + 6 | john + 7 | tim + (7 rows) + ``` + + - 删除数据表快照SNAPSHOT + + ```sql + purge snapshot s1@3.0; + schema | name + --------+-------- + public | s1@3.0 + (1 row) + ``` + + 此时,已经无法再从 `s1@3.0` 中检索到数据了,同时该数据表快照在db4ai.snapshot视图中的记录也会被清除。删除该版本的数据表快照不会影响其他版本的数据表快照。 + + - 从数据表快照中采样 + + 示例:从snapshot s1中抽取数据,使用0.5抽样率。 + + ```sql + sample snapshot s1@2.0 stratify by name as nick at ratio .5; + schema | name + --------+------------ + public | s1nick@2.0 + (1 row) + ``` + + 可以利用该功能创建训练集与测试集,例如: + + ```sql + SAMPLE SNAPSHOT s1@2.0 STRATIFY BY name AS _test AT RATIO .2, AS _train AT RATIO .8 COMMENT IS 'training'; + schema | name + --------+---------------- + public | s1_test@2.0 + public | s1_train@2.0 + (2 rows) + ``` + + - 发布数据表快照 + + 采用下述SQL语句将数据表快照 s1@2.0 标记为published 状态: + + ```sql + publish snapshot s1@2.0; + schema | name + --------+-------- + public | s1@2.0 + (1 row) + ``` + + - 存档数据表快照 + + 采用下述语句可以将数据表快照标记为 archived 状态: + + ```sql + archive snapshot s1@2.0; + schema | name + --------+-------- + public | s1@2.0 + (1 row) + ``` + + 可以通过db4ai-snapshots提供的视图查看当前数据表快照的状态以及其他信息: + + ```sql + select * from db4ai.snapshot; + id | parent_id | matrix_id | root_id | schema | name | owner | commands | comment | published | archived | created | row_count + ----+-----------+-----------+---------+--------+------------+--------+------------------------------------------+---------+-----------+----------+----------------------------+----------- + 1 | | | 1 | public | s1@2.0 | omm | {"select *","from t1 where id > 3",NULL} | | t | f | 2021-04-17 09:24:11.139868 | 2 + 2 | 1 | | 1 | public | s1nick@2.0 | omm | {"SAMPLE nick .5 {name}"} | | f | f | 2021-04-17 10:02:31.73923 | 0 + ``` + +3. 异常场景 + + - 数据表或db4ai-snapshots不存在时。 + + ```sql + purge snapshot s1nick@2.0; + publish snapshot s1nick@2.0; + --------- + ERROR: snapshot public."s1nick@2.0" does not exist + CONTEXT: PL/pgSQL function db4ai.publish_snapshot(name,name) line 11 at assignment + + archive snapshot s1nick@2.0; + ---------- + ERROR: snapshot public."s1nick@2.0" does not exist + CONTEXT: PL/pgSQL function db4ai.archive_snapshot(name,name) line 11 at assignment + ``` + + - 删除snapshot时,有依赖该快照的其他snapshot,需先确保删除对本快照所依赖的其他快照。 + + ```sql + purge snapshot s1@1.0; + ERROR: cannot purge root snapshot 'public."s1@1.0"' having dependent snapshots + HINT: purge all dependent snapshots first + CONTEXT: referenced column: purge_snapshot_internal + SQL statement "SELECT db4ai.purge_snapshot_internal(i_schema, i_name)" + PL/pgSQL function db4ai.purge_snapshot(name,name) line 71 at PERFORM + ``` + +4. 相关GUC参数 + + - db4ai_snapshot_mode: + + Snapshot有2种模式:MSS(物化模式,存储数据实体)和CSS(计算模式,存储增量信息)。Snapshot可在MSS和CSS之间切换快照模式,默认是MSS模式。 + + - db4ai_snapshot_version_delimiter: + + 该参数为数据表快照版本分隔符。“@” 为数据表快照的默认版本分隔符。 + + - db4ai_snapshot_version_separator + + 该参数为数据表快照子版本分隔符。“.”为数据表快照的默认版本分隔符。 + +5. DB4AI Schema下的数据表快照详情db4ai.snapshot。 + + ```sql + MogDB=# \d db4ai.snapshot + Table "db4ai.snapshot" + Column | Type | Modifiers + -----------+-----------------------------+--------------------------- + id | bigint | + parent_id | bigint | + matrix_id | bigint | + root_id | bigint | + schema | name | not null + name | name | not null + owner | name | not null + commands | text[] | not null + comment | text | + published | boolean | not null default false + archived | boolean | not null default false + created | timestamp without time zone | default pg_systimestamp() + row_count | bigint | not null + Indexes: + "snapshot_pkey" PRIMARY KEY, btree (schema, name) TABLESPACE pg_default + "snapshot_id_key" UNIQUE CONSTRAINT, btree (id) TABLESPACE pg_default + ``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 命名空间DB4AI是本功能的私有域,不支持在DB4AI的命令空间下创建函数索引(functional index)。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/full-process-ai.md b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/full-process-ai.md new file mode 100644 index 00000000..f7f8d8d6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/full-process-ai.md @@ -0,0 +1,12 @@ +--- +title: 全流程AI +summary: 全流程AI +author: Guo Huan +date: 2022-05-06 +--- + +# 全流程AI + +传统的AI任务往往具有多个流程,如数据的收集过程包括数据的采集、数据清洗、数据存储等,在算法的训练过程中又包括数据的预处理、训练、模型的保存与管理等。其中,对于模型的训练过程,又包括超参数的调优过程。诸如此类机器学习模型生命周期的全过程,可大量集成于数据库内部。在距离数据存储侧最近处进行模型的训练、管理、优化等流程,在数据库端提供SQL语句式的开箱即用的AI全声明周期管理的功能,称之为全流程AI. + +MogDB实现了部分全流程AI的功能,将在本章节中详细展开。 diff --git a/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/plpython-fenced-mode.md b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/plpython-fenced-mode.md new file mode 100644 index 00000000..1f98de0b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/full-process-ai/plpython-fenced-mode.md @@ -0,0 +1,135 @@ +--- +title: PLPython Fenced模式 +summary: PLPython Fenced模式 +author: Guo Huan +date: 2022-05-06 +--- + +# PLPython Fenced模式 + +在fenced模式中添加plpython非安全语言。在数据库编译时需要将python集成进数据库中,在configure阶段加入--with-python选项。同时也可指定安装plpython的python路径,添加选项--with-includes='/python-dir=path'。 + +在启动数据库之前配置GUC参数unix_socket_directory ,指定unix_socket进程间通讯的文件地址。用户需要提前在user-set-dir-path下创建文件夹,并将文件夹权限修改为可读可写可执行状态。 + +``` +unix_socket_directory = '/user-set-dir-path' +``` + +配置完成,启动数据库。 + +将plpython加入数据库编译,并设置好GUC参数unix_socket_directory后,在启动数据库的过程中,自动创建fenced-Master进程。在数据库不进行python编译的情况下,fenced模式需要手动拉起master进程,在GUC参数设置完成后,输入创建master进程命令。 + +启动fenced-Master进程,命令为: + +``` +gaussdb --fenced -k /user-set-dir-path -D /user-set-dir-path & +``` + +完成fence模式配置,针对plpython-fenced UDF数据库将在fenced-worker进程中执行UDF计算。 + +## 使用指导 + +- 创建extension + + - 当编译的plpython为python2时: + + ``` + MogDB=# create extension plpythonu; + CREATE EXTENSION + ``` + + - 当编译的plpython为python3时: + + ``` + MogDB=# create extension plpython3u; + CREATE EXTENSION + ``` + + 下面示例是以python2为例。 + +- 创建plpython-fenced UDF + + ``` + MogDB=# create or replace function pymax(a int, b int) + MogDB-# returns INT + MogDB-# language plpythonu fenced + MogDB-# as $$ + MogDB$# import numpy + MogDB$# if a > b: + MogDB$# return a; + MogDB$# else: + MogDB$# return b; + MogDB$# $$; + CREATE FUNCTION + ``` + +- 查看UDF信息 + + ``` + MogDB=# select * from pg_proc where proname='pymax'; + -[ RECORD 1 ]----+-------------- + proname | pymax + pronamespace | 2200 + proowner | 10 + prolang | 16388 + procost | 100 + prorows | 0 + provariadic | 0 + protransform | - + proisagg | f + proiswindow | f + prosecdef | f + proleakproof | f + proisstrict | f + proretset | f + provolatile | v + pronargs | 2 + pronargdefaults | 0 + prorettype | 23 + proargtypes | 23 23 + proallargtypes | + proargmodes | + proargnames | {a,b} + proargdefaults | + prosrc | + | import numpy + | if a > b: + | return a; + | else: + | return b; + | + probin | + proconfig | + proacl | + prodefaultargpos | + fencedmode | t + proshippable | f + propackage | f + prokind | f + proargsrc | + ``` + +- 运行UDF + + - 创建一个数据表: + + ``` + MogDB=# create table temp (a int ,b int) ; + CREATE TABLE + MogDB=# insert into temp values (1,2),(2,3),(3,4),(4,5),(5,6); + INSERT 0 5 + ``` + + - 运行UDF: + + ``` + MogDB=# select pymax(a,b) from temp; + pymax + ------- + 2 + 3 + 4 + 5 + 6 + (5 rows) + ``` diff --git a/product/zh/docs-mogdb/v3.1/AI-features/db4ai/native-db4ai-engine.md b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/native-db4ai-engine.md new file mode 100644 index 00000000..0b249e4b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/AI-features/db4ai/native-db4ai-engine.md @@ -0,0 +1,317 @@ +--- +title: 原生DB4AI引擎 +summary: 原生DB4AI引擎 +author: Guo Huan +date: 2022-05-06 +--- + +# DB4AI: 数据库驱动AI + +MogDB当前版本支持了原生DB4AI能力,通过引入原生AI算子,简化操作流程,充分利用数据库优化器、执行器的优化与执行能力,获得高性能的数据库内模型训练能力。更简化的模型训练与预测流程、更高的性能表现,让开发者在更短时间内能更专注于模型的调优与数据分析上,而避免了碎片化的技术栈与冗余的代码实现。 + +## 关键字解析 + +**表 1** DB4AI语法及关键字 + +| 名称 | | 描述 | +| :----- | :----------- | ---------------------------------- | +| 语法 | CREATE MODEL | 创建模型并进行训练,同时保存模型。 | +| | PREDICT BY | 利用已有模型进行推断。 | +| | DROP MODEL | 删除模型。 | +| 关键字 | TARGET | 训练/推断任务的目标列名。 | +| | FEATURES | 训练/推断任务的数据特征列名。 | +| | MODEL | 训练任务的模型名称。 | + +## 使用指导 + +1. 本版本支持的算法概述。 + + 当前版本的DB4AI新增支持算法如下: + + **表 2** 支持算法 + + | 优化算法 | 算法 | + | :------- | :------------------------------ | + | GD | logistic_regression | + | | linear_regression | + | | svm_classification | + | | PCA | + | | multiclass | + | Kmeans | kmeans | + | xgboost | xgboost_regression_logistic | + | | xgboost_binary_logistic | + | | xgboost_regression_squarederror | + | | xgboost_regression_gamma | + +2. 模型训练语法说明。 + + - CREATE MODEL + + 使用“CREATE MODEL”语句可以进行模型的创建和训练。模型训练SQL语句,选用公开数据集鸢尾花数据集iris。 + + - 以multiclass为例,训练一个模型。从tb_iris训练集中指定sepal_length, sepal_width,petal_length,petal_widt为特征列,使用multiclass算法,创建并保存模型iris_classification_model。 + + ``` + MogDB=# CREATE MODEL iris_classification_model USING xgboost_regression_logistic FEATURES sepal_length, sepal_width,petal_length,petal_width TARGET target_type < 2 FROM tb_iris_1 WITH nthread=4, max_depth=8; + MODEL CREATED. PROCESSED 1 + ``` + + 上述命令中: + + - “CREATE MODEL”语句用于模型的训练和保存。 + + - USING关键字指定算法名称。 + + - FEATURES用于指定训练模模型的特征,需根据训练数据表的列名添加。 + + - TARGET指定模型的训练目标,它可以是训练所需数据表的列名,也可以是一个表达式,例如: price > 10000。 + + - WITH用于指定训练模型时的超参数。当超参未被用户进行设置的时候,框架会使用默认数值。 + + 针对不同的算子,框架支持不同的超参组合: + + **表 3** 算子支持的超参 + + | 算子 | 超参 | + | :----------------------------------------------------------- | :----------------------------------------------------------- | + | GD
(logistic_regression、linear_regression、svm_classification) | optimizer(char); verbose(bool); max_iterations(int); max_seconds(double); batch_size(int); learning_rate(double); decay(double); tolerance(double)
其中,SVM限定超参lambda(double) | + | Kmeans | max_iterations(int); num_centroids(int); tolerance(double); batch_size(int); num_features(int); distance_function(char); seeding_function(char); verbose(int);seed(int) | + | GD(pca) | batch_size(int);max_iterations(int);max_seconds(int);tolerance(float8);verbose(bool);number_components(int);seed(int) | + | GD(multiclass) | classifier(char)
注意:multiclass的其他超参种类取决于选择的分类器中类 | + | xgboost_regression_logistic、xgboost_binary_logistic、xgboost_regression_squarederror、xgboost_regression_gamma | batch_size(int);booster(char);tree_method(char);eval_metric(char);seed(int);nthread(int);max_depth(int);gamma(float8);eta(float8);min_child_weight(int);verbosity(int) | + + 当前各个超参数设置的默认值和取值范围如下: + + **表 4** 超参的默认值以及取值范围 + + | 算子 | 超参(默认值) | 取值范围 | 超参描述 | + | :----------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------------- | :---------------------------------------- | + | GD:logistic_regression、linear_regression、svm_classification、pca | optimizer = gd(梯度下降法) | gd/ngd(自然梯度下降) | 优化器 | + | | verbose = false | T/F | 日志显示 | + | | max_iterations = 100 | (0, 10000] | 最大迭代次数 | + | | max_seconds = 0 (不对运行时长设限制) | [0,INT_MAX_VALUE] | 运行时长 | + | | batch_size = 1000 | (0, 1048575] | 一次训练所选取的样本数 | + | | learning_rate = 0.8 | (0, DOUBLE_MAX_VALUE] | 学习率 | + | | decay = 0.95 | (0, DOUBLE_MAX_VALUE] | 权值衰减率 | + | | tolerance = 0.0005 | (0, DOUBLE_MAX_VALUE] | 公差 | + | | seed = 0(对seed取随机值) | [0, INT_MAX_VALUE] | 种子 | + | | just for linear、SVM:kernel = “linear” | linear/gaussian/polynomial | 核函数 | + | | just for linear、SVM:components = MAX(2*features, 128) | [0, INT_MAX_VALUE] | 高维空间维数 | + | | just for linear、SVM:gamma = 0.5 | (0, DOUBLE_MAX_VALUE] | gaussian核函数参数 | + | | just for linear、SVM:degree = 2 | [2, 9] | polynomial核函数参数 | + | | just for linear、SVM:coef0 = 1.0 | [0, DOUBLE_MAX_VALUE] | polynomial核函数的参数 | + | | just for SVM:lambda = 0.01 | (0, DOUBLE_MAX_VALUE) | 正则化参数 | + | | just for pca: number_components | (0,INT_MAX_VALUE] | 降维的目标维度 | + | GD:multiclass | classifier=“svm_classification” | svm_classification\logistic_regression | 多分类任务的分类器 | + | Kmeans | max_iterations = 10 | [1, 10000] | 最大迭代次数 | + | | num_centroids = 10 | [1, 1000000] | 簇的数目 | + | | tolerance = 0.00001 | (0,1] | 中心点误差 | + | | batch_size = 10 | [1,1048575] | 一次训练所选取的样本数 | + | | num_features = 2 | [1, INT_MAX_VALUE] | 输入样本特征数 | + | | distance_function = “L2_Squared” | L1\L2\L2_Squared\Linf | 正则化方法 | + | | seeding_function = “Random++” | “Random++”\“KMeans | | + | | verbose = 0U | { 0, 1, 2 } | 冗长模式 | + | | seed = 0U | [0, INT_MAX_VALUE] | 种子 | + | xgboost:
xgboost_regression_logistic、xgboost_binary_logistic、xgboost_regression_gamma、xgboost_regression_squarederror | n_iter=10 | (0, 10000] | 迭代次数 | + | | batch_size=10000 | (0, 1048575] | 一次训练所选取的样本数 | + | | booster=“gbtree” | gbtree\gblinear\dart | booster种类 | + | | tree_method=“auto” | auto\exact\approx\hist\gpu_hist
注意:gpu_hist参数需要相应的库GPU版本,否则DB4AI平台不支持该值。 | 树构建算法 | + | | eval_metric=“rmse” | rmse\rmsle\map\mae\auc\aucpr | 验证数据的评估指标 | + | | seed=0 | [0, 100] | 种子 | + | | nthread=1 | (0, MAX_MEMORY_LIMIT] | 并发量 | + | | max_depth=5 | (0, MAX_MEMORY_LIMIT] | 树的最大深度,该超参仅对树型booster生效。 | + | | gamma=0.0 | [0, 1] | 叶节点上进行进一步分区所需的最小损失减少 | + | | eta=0.3 | [0, 1] | 更新中使用的步长收缩,以防止过拟合 | + | | min_child_weight=1 | [0, INT_MAX_VALUE] | 孩子节点中所需的实例权重的最小总和 | + | | verbosity=1 | 0 (silent)\1 (warning)\2 (info)\3 (debug) | 打印信息的详细程度 | + | MAX_MEMORY_LIMIT = 最大内存加载的元组数量 | | | | + | GS_MAX_COLS = 数据库单表最大属性数量 | | | | + + - 模型保存成功,则返回创建成功信息: + + ``` + MODEL CREATED. PROCESSED x + ``` + +3. 查看模型信息。 + + 当训练完成后模型会被存储到系统表gs_model_warehouse中。系统表gs_model_warehouse可以查看到关于模型本身和训练过程的相关信息。 + + 关于模型的详细描述信息以二进制的形式存储在系统表中,用户可用过使用函数gs_explain_model完成对模型的查看,语句如下: + + ``` + MogDB=# select * from gs_explain_model("iris_classification_model"); + DB4AI MODEL + ------------------------------------------------------------- + Name: iris_classification_model + Algorithm: xgboost_regression_logistic + Query: CREATE MODEL iris_classification_model + USING xgboost_regression_logistic + FEATURES sepal_length, sepal_width,petal_length,petal_width + TARGET target_type < 2 + FROM tb_iris_1 + WITH nthread=4, max_depth=8; + Return type: Float64 + Pre-processing time: 0.000000 + Execution time: 0.001443 + Processed tuples: 78 + Discarded tuples: 0 + n_iter: 10 + batch_size: 10000 + max_depth: 8 + min_child_weight: 1 + gamma: 0.0000000000 + eta: 0.3000000000 + nthread: 4 + verbosity: 1 + seed: 0 + booster: gbtree + tree_method: auto + eval_metric: rmse + rmse: 0.2648450136 + model size: 4613 + ``` + +4. 利用已存在的模型做推断任务。 + + 使用“SELECT”和“PREDICT BY”关键字利用已有模型完成推断任务。 + + 查询语法:SELECT…PREDICT BY…(FEATURES…)…FROM…; + + ``` + MogDB=# SELECT id, PREDICT BY iris_classification (FEATURES sepal_length,sepal_width,petal_length,petal_width) as "PREDICT" FROM tb_iris limit 3; + + id | PREDICT + -----+--------- + 84 | 2 + 85 | 0 + 86 | 0 + (3 rows) + ``` + + 针对相同的推断任务,同一个模型的结果是大致稳定的。且基于相同的超参数和训练集训练的模型也具有稳定性,同时AI模型训练存在随机成分(每个batch的数据分布、随机梯度下降),所以不同的模型间的计算表现、结果允许存在小的差别。 + +5. 查看执行计划。 + + 使用explain语句可对“CREATE MODEL”和“PREDICT BY”的模型训练或预测过程中的执行计划进行分析。Explain关键字后可直接拼接CREATE MODEL/ PREDICT BY语句(子句),也可接可选的参数,支持的参数如下: + + **表 5** EXPLAIN支持的参数 + + | 参数名 | 描述 | + | :-------- | :--------------------------------------------- | + | ANALYZE | 布尔型变量,追加运行时间、循环次数等描述信息 | + | VERBOSE | 布尔型变量,控制训练的运行信息是否输出到客户端 | + | COSTS | 布尔型变量 | + | CPU | 布尔型变量 | + | DETAIL | 布尔型变量,不可用。 | + | NODES | 布尔型变量,不可用 | + | NUM_NODES | 布尔型变量,不可用 | + | BUFFERS | 布尔型变量 | + | TIMING | 布尔型变量 | + | PLAN | 布尔型变量 | + | FORMAT | 可选格式类型:TEXT / XML / JSON / YAML | + + 示例: + + ``` + MogDB=# Explain CREATE MODEL patient_logisitic_regression USING logistic_regression FEATURES second_attack, treatment TARGET trait_anxiety > 50 FROM patients WITH batch_size=10, learning_rate = 0.05; + QUERY PLAN + ------------------------------------------------------------------------- + Train Model - logistic_regression (cost=0.00..0.00 rows=0 width=0) + -> Materialize (cost=0.00..41.08 rows=1776 width=12) + -> Seq Scan on patients (cost=0.00..32.20 rows=1776 width=12) + (3 rows) + ``` + +6. 异常场景。 + + - 训练阶段。 + + - 场景一:当超参数的设置超出取值范围,模型训练失败,返回ERROR,并提示错误,例如: + + ``` + MogDB=# CREATE MODEL patient_linear_regression USING linear_regression FEATURES second_attack,treatment TARGET trait_anxiety FROM patients WITH optimizer='aa'; + ERROR: Invalid hyperparameter value for optimizer. Valid values are: gd, ngd. + ``` + + - 场景二:当模型名称已存在,模型保存失败,返回ERROR,并提示错误原因,例如: + + ``` + MogDB=# CREATE MODEL patient_linear_regression USING linear_regression FEATURES second_attack,treatment TARGET trait_anxiety FROM patients; + ERROR: The model name "patient_linear_regression" already exists in gs_model_warehouse. + ``` + + - 场景三:FEATURE或者TARGETS列是*,返回ERROR,并提示错误原因,例如: + + ``` + MogDB=# CREATE MODEL patient_linear_regression USING linear_regression FEATURES * TARGET trait_anxiety FROM patients; + ERROR: FEATURES clause cannot be * + ----------------------------------------------------------------------------------------------------------------------- + MogDB=# CREATE MODEL patient_linear_regression USING linear_regression FEATURES second_attack,treatment TARGET * FROM patients; + ERROR: TARGET clause cannot be * + ``` + + - 场景四:对于无监督学习方法使用TARGET关键字,或者在监督学习方法中不适用TARGET关键字,均会返回ERROR,并提示错误原因,例如: + + ``` + MogDB=# CREATE MODEL patient_linear_regression USING linear_regression FEATURES second_attack,treatment FROM patients; + ERROR: Supervised ML algorithms require TARGET clause + ----------------------------------------------------------------------------------------------------------------------------- + CREATE MODEL patient_linear_regression USING linear_regression TARGET trait_anxiety FROM patients; + ERROR: Supervised ML algorithms require FEATURES clause + ``` + + - 场景五:当进行分类任务时TARGET列的分类只有1种情况,会返回ERROR,并提示错误原因,例如: + + ``` + MogDB=# CREATE MODEL ecoli_svmc USING multiclass FEATURES f1, f2, f3, f4, f5, f6, f7 TARGET cat FROM (SELECT * FROM db4ai_ecoli WHERE cat='cp'); + ERROR: At least two categories are needed + ``` + + - 场景六:DB4AI在训练过程中会过滤掉含有空值的数据,当参与训练的模型数据为空的时候,会返回ERROR,并提示错误原因,例如: + + ``` + MogDB=# create model iris_classification_model using xgboost_regression_logistic features message_regular target error_level from error_code; + ERROR: Training data is empty, please check the input data. + ``` + + - 场景七:DB4AI的算法对于支持的数据类型是有限制的。当数据类型不在支持白名单中,会返回ERROR,并提示非法的oid,可通过pg_type查看OID确定非法的数据类型,例如: + + ``` + MogDB=# CREATE MODEL ecoli_svmc USING multiclass FEATURES f1, f2, f3, f4, f5, f6, f7, cat TARGET cat FROM db4ai_ecoli ; + ERROR: Oid type 1043 not yet supported + ``` + + - 场景八:当GUC参数statement_timeout设置了时长,训练超时执行的语句将被终止:执行CREATE MODEL语句。训练集的大小、训练轮数(iteration)、提前终止条件(tolerance、max_seconds)、并行线程数(nthread)等参数都会影响训练时长。当时长超过数据库限制,语句被终止模型训练失败。 + + - 模型解析。 + + - 场景九:当模型名在系统表中查找不到,数据库会报ERROR,例如: + + ``` + MogDB=# select gs_explain_model("ecoli_svmc"); + ERROR: column "ecoli_svmc" does not exist + ``` + + - 推断阶段。 + + - 场景十:当模型名在系统表中查找不到,数据库会报ERROR,例如: + + ``` + MogDB=# select id, PREDICT BY patient_logistic_regression (FEATURES second_attack,treatment) FROM patients; + ERROR: There is no model called "patient_logistic_regression". + ``` + + - 场景十一:当做推断任务FEATURES的数据维度和数据类型与训练集存在不一致,将报ERROR,并提示错误原因,例如: + + ``` + MogDB=# select id, PREDICT BY patient_linear_regression (FEATURES second_attack) FROM patients; + ERROR: Invalid number of features for prediction, provided 1, expected 2 + CONTEXT: referenced column: patient_linear_regression_pred + ------------------------------------------------------------------------------------------------------------------------------------- + MogDB=# select id, PREDICT BY patient_linear_regression (FEATURES 1,second_attack,treatment) FROM patients; + ERROR: Invalid number of features for prediction, provided 3, expected 2 + CONTEXT: referenced column: patient_linear_regression_pre + ``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: DB4AI特性需要读取数据参与计算,不适用于密态数据库等情况。 diff --git a/product/zh/docs-mogdb/v3.1/_index.md b/product/zh/docs-mogdb/v3.1/_index.md new file mode 100644 index 00000000..528656ec --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/_index.md @@ -0,0 +1,90 @@ +--- +title: Introduction +summary: SELECT +author: Zhang Cuiping +date: 2022-08-07 +--- + + + + + +[MogDB简介](./overview.md) + +[特性描述](./characteristic-description/characteristic-description-overview.md) + +[发布说明](./about-mogdb/mogdb-new-feature/release-note.md) + + + + + +[MogDB实训环境](./quick-start/mogdb-playground.md) + + + + + +[使用PTK安装MogDB](./installation-guide/ptk-based-installation.md) + +[MogDB in Container](./installation-guide/docker-installation/docker-installation.md) + +[MogDB on Kubernetes](../../docs-mogdb-stack/v1.0/quick-start.md) + + + + + +[基于JDBC开发](./developer-guide/dev/2-development-based-on-jdbc/3-development-process.md) + +[数据导入/导出](./administrator-guide/importing-and-exporting-data/importing-data/1-import-modes.md) + + + + + +[日常运维](./administrator-guide/routine-maintenance/0-starting-and-stopping-mogdb.md) + +[备份与恢复](./administrator-guide/br/1-1-br.md) + +[升级指南](./administrator-guide/upgrade-guide.md) + +[故障诊断指南](./common-faults-and-identification/common-fault-locating-methods.md) + +[使用MogDB Stack](../../docs-mogdb-stack/v1.0/overview.md) + +[MogHA高可用管理](../../docs-mogha/v2.3/overview.md) + +[MogDB命令集](./reference-guide/tool-reference/tool-overview.md) + + + + + +[系统优化指南](./performance-tuning/1-system/1-optimizing-os-parameters.md) + +[SQL优化指南](./performance-tuning/2-sql/1-query-execution-process.md) + +[WDR解读指南](./performance-tuning/3-wdr/wdr-snapshot-schema.md) + +[TPCC测试优化指南](./performance-tuning/TPCC-performance-tuning-guide.md) + + + + + +[PTK部署运维工具](../../docs-ptk/v0.4/overview.md) + +[MTK异构数据库迁移](../../docs-mtk/v2.0/overview.md) + +[SCA兼容性分析](../../docs-sca/v5.1/overview.md) + +[MVD数据一致性校验](../../docs-mvd/v2.4/overview.md) + +[MDB异构数据同步](../../docs-mdb/v1.0/overview.md) + +[Mogeaver图形化工具](./mogeaver/mogeaver-overview.md) + + + + diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/MogDB-compared-to-openGauss.md b/product/zh/docs-mogdb/v3.1/about-mogdb/MogDB-compared-to-openGauss.md new file mode 100644 index 00000000..8f84f310 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/MogDB-compared-to-openGauss.md @@ -0,0 +1,134 @@ +--- +title: MogDB与openGauss +summary: MogDB与openGauss +author: Guo Huan +date: 2021-03-30 +--- + +# MogDB与openGauss + +
+ +## MogDB与openGauss的关系 + +MogDB是在openGauss开源内核的基础上封装和改善的对于企业应用更加友好的企业级数据库。在openGauss内核的基础上,MogDB增加了MogHA组件,用于进行主备架构下高可用的自动化管理,这对于企业级应用来说是至关重要的。同时也同步研发了MogDB Manager管理软件,其中包括备份恢复,监控,自动化安装等等针对企业级易用性需求的组件。 + +MogDB是一款商业产品,按照既定的License价格体系销售,同时享有云和恩墨的专业服务支持。 + +
+ +## 关于openGauss + +openGauss是一款开源关系型数据库管理系统,openGauss内核源自PostgreSQL,采用木兰宽松许可证v2发行。openGauss内核是开源的,任何人任何组织都可以自行下载源码进行编译安装使用,无需任何费用;openGauss社区也会定期发布编译好的二进制安装文件,目前的发布策略是每年发布一个稳定常支持版本(每年3月底)和一个新功能激进版本(每年9月底)。 + +openGauss是一个单机数据库,具备关系型数据库的基本功能,以及企业特性的增强功能。 + +更多详情请访问openGauss官方网站: + +
+ +### 基本功能 + +- 标准SQL支持 + + 支持标准的SQL92/SQL99/SQL2003/SQL2011规范,支持GBK和UTF-8字符集,支持SQL标准函数与分析函数,支持存储过程。 + +- 数据库存储管理功能 + + 支持表空间,可以把不同表规划到不同的存储位置。 + +- 提供主备双机 + + 事务支持ACID特性、单节点故障恢复、双机数据同步,双机故障切换等。 + +- 应用程序接口 + + 支持标准JDBC 4.0的特性、ODBC 3.5特性。 + +- 管理工具 + + 提供安装部署工具、实例启停工具、备份恢复工具。 + +- 安全管理 + + 支持SSL安全网络连接、用户权限管理、密码管理、安全审计等功能,保证数据库在管理层、应用层、系统层和网络层的安全性。 + +
+ +### 企业级增强特性 + +- 数据分区 + + 数据分区是数据库产品普遍具备的功能。在openGauss中,数据分区是对数据按照用户指定的策略对数据做的水平分表,将表按照指定范围划分为多个数据互不重叠的部分(Partition)。 + +- 向量化执行和行列混合引擎 + + 在大宽表,数据量比较大、查询经常关注某些列的场景中,行存储引擎查询性能比较差。例如气象局的场景,单表有200~800个列,查询经常访问10个列,在类似这样的场景下,向量化执行技术和列存储引擎可以极大的提升性能和减少存储空间。 + +- 高可靠事务处理 + + openGauss提供事务管理功能,保证事务的ACID特性。为了在主节点出现故障时尽可能地不中断服务,openGauss提供了主备双机高可靠机制。通过保护关键用户程序对外不间断提供服务,把因为硬件、软件和人为造成的故障对业务的影响程度降到最低,以保证业务的持续性。 + +- 高并发&高性能 + + openGauss通过服务器端的线程池,可以支持1W并发连接。通过NUMA化内核数据结构,支持线程亲核性处理,可以支持百万级tpmC。通过页面的高效冷热淘汰,支持T级别大内存缓冲区管理。通过CSN快照,去除快照瓶颈,实现多版本访问,读写互不阻塞。通过增量检查点,避免全页写导致的性能波动,实现业务性能平稳运行。 + +- SQL自诊断 + + 通过执行查询对应的explain performance,获得对应执行计划,是一种十分有效的定位查询性能问题的方法。但是这种方法需要修改业务逻辑,同时输出的日志量大,问题定位的效率依赖于人员的经验。SQL自诊断为用户提供了另一种更为高效易用的性能问题定位方法。 + +- 全密态数据库等值查询 + + 密态数据库允许客户端对客户端应用程序内的敏感数据进行加密。在查询期间,整个业务数据流在数据处理过程中都是以密文形态存在。优势如下: + + - 保护数据在云上全生命周期的隐私安全; + - 通过将密钥掌握在用户自己手上,实现公有云、消费者云以及开发用户的用户信任问题; + - 让云数据库借助全密态能力更好的遵守个人隐私保护方面的法律法规。 + +- 内存表 + + 内存表把数据全部缓存在内存中,所有数据访问实现免锁并发,实现数据处理的极致性能,满足实时性严苛要求场景。 + +- 主备双机 + + 主备双机支持同步和异步复制,应用可以根据业务场景选择合适的部署方式。同步复制保证数据的高可靠,一般需要一主两备部署,同时对性能有一定影响。异步复制一主一备部署即可,对性能影响小,但异常时可能存在数据丢失。openGauss支持页面损坏的自动修复,在主机页面发生损坏时,能够自动从备机修复损坏页面。openGauss支持备机并行日志恢复,尽量降低主机故障时业务不可用的时间。 + + 同时,如果按照主备模式部署,并打开备机可读功能后,备机将能够提供读操作,但不支持写操作(如建表、插入数据、删除数据等),从而缓解主机上的压力。 + +- 具备AI能力 + + - 参数自动调优 + - 慢SQL发现 + - 索引推荐 + - 时序预测与异常检测 + - 支持DB4AI功能 + - SQL执行时间预测 + - 数据库监控 + +- 逻辑日志复制 + + 在逻辑复制中把主库称为源端库,备库称为目标端数据库,源端数据库根据预先指定好的逻辑解析规则对WAL文件进行解析,把DML操作解析成一定的逻辑变化信息(标准SQL语句),源端数据库把标准SQL语句发给目标端数据库,目标端数据库收到后进行应用,从而实现数据同步。逻辑复制只有DML操作。逻辑复制可以实现跨版本复制,异构数据库复制,双写数据库复制,表级别复制。 + +- 支持WDR自动性能分析报告 + + 定时主动分析run日志和WDR报告(自动后台生成,可由关键指标阈值如CPU占用率、内存占用率、长SQL比例等触发),并生成html、pdf等格式的报告。能自动生成性能报告。WDR(Workload Diagnosis Report)基于两次不同时间点系统的性能快照数据, 生成这两个时间点之间的性能表现报表,用于诊断数据库内核的性能故障。 + +- 增量备份/恢复(beta) + + 支持对数据库进行全量备份和增量备份,支持对备份数据进行管理,查看备份状态。支持增量备份的合并,过期备份的删除。数据库服务器动态跟踪页面更改,每当一个关系页被更新时,这个页就会被标记为需要备份。增量备份功能需要打开GUC参数 enable_cbm_tracking,以便允许服务器跟踪修改页。 + +- 恢复到指定时间点(PITR) + + 时间点恢复(Point In Time Recovery)基本原理是通过基础热备 + WAL预写日志 + WAL归档日志进行备份恢复。重放WAL记录的时候可以在任意点停止重放,这样就有一个在任意时间的数据库一致的快照。即可以把数据库恢复到自开始备份以来的任意时刻的状态。在恢复时可以指定恢复的停止点位置为TID,时间和LSN。 + +
+ +## MogDB的优势 + +openGauss是单机系统,在这样的系统架构中,业务数据存储在单个物理节点上,数据访问任务被推送到服务节点执行,通过服务器的高并发,实现对数据处理的快速响应。同时通过日志复制可以把数据复制到备机,提供数据的高可靠和读扩展。 + +openGauss为单一数据库内核,若要在正式的商业项目上使用,还需要构筑数据库监控、主备切换等完整工具链的能力。 + +在产品层面,MogDB在openGauss原有功能的基础上增加了MogHA企业级高可用组件,以及功能丰富的图形化管理工具MogDB Manager,并在既定路线上持续不断对openGauss内核进行增强。MogDB可最大限度地保障多机房高可用部署能力,4路服务器上可以达到250万tpmC。MogDB Manager包含多种实用组件,如MogHA高可用管理、MTK异构数据库迁移、PTK部署运维、MDB异构数据同步、SCA兼容性分析以及MVD数据一致性校验工具等,极大程度上完善了openGauss开源数据库的不足之处,丰富了各项企业级功能。 + +在服务层面,云和恩墨拥有数十年的数据库运维经验,可提供完整的兜底服务,确保数据库更加稳定,应用改造更加平滑,风险更小,弥补openGauss开源数据库人力运维不足的劣势,同时降低维护成本。 diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.0.md b/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.0.md new file mode 100644 index 00000000..375c7215 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.0.md @@ -0,0 +1,193 @@ +--- +title: MogDB 3.0.0 +summary: MogDB 3.0.0 +author: Guo Huan +date: 2022-05-30 +--- + +# MogDB 3.0.0 + +## 1. 版本说明 + +MogDB 3.0.0版本于2022年6月30日发布。3.0.0版本基于2.1版本进一步增强,并合入了openGauss 3.0.0版本的新增特性。 + +
+ +## 2. 新增特性 + +### 2.1 集成openGauss 3.0.0版本新特性 + +- [行存转向量化](../../characteristic-description/high-performance/12-row-store-execution-to-vectorized-execution.md) +- [延迟进入最大可用模式](../../characteristic-description/high-availability/11-delaying-entering-the-maximum-availability-mode.md) +- [并行逻辑解码](../../characteristic-description/high-availability/12-parallel-logical-decoding.md) +- [CM(Cluster Manager)](../../reference-guide/tool-reference/unified-database-management-tool.md) +- [Global Syscache](../../characteristic-description/high-availability/15-global-syscache.md) +- [发布订阅](../../characteristic-description/enterprise-level-features/16-publication-subscription.md) +- [外键锁增强](../../characteristic-description/enterprise-level-features/17-foreign-key-lock-enhancement.md) +- [支持ANY权限管理](../../reference-guide/sql-syntax/GRANT.md) +- [DBMind组件化](../../AI-features/ai4db/ai4db-autonomous-database-o&m.md) +- [库内AI算法支持XGBoost、multiclass和PCA](../../AI-features/db4ai/native-db4ai-engine.md) +- [支持使用中间件ShardingSphere构建分布式数据库](../../characteristic-description/middleware/distributed-database-capability.md) + +### 2.2 自治事务异步提交 + +- 将事务执行和事务日志落盘拆分为由两个不同线程执行,避免事务等待阶段Session worker线程闲置,进一步提高了worker线程的利用率,在保障数据完整性的基础上进一步提升了数据库性能。 +- 自治事务异步提交可以使数据库整体性能提升20%~50%,TPCC压测下tpmC稳定提升36%。 + +**相关页面**:[事务异步提交](../../characteristic-description/enterprise-level-features/19-transaction-async-submit.md) + +### 2.3 索引创建并行控制 + +- 在创建索引时,可以指定参数控制并行度,使索引创建更加高效灵活。 + +**相关页面**:[索引创建并行控制](../../characteristic-description/enterprise-level-features/23-index-creation-parallel-control.md) + +### 2.4 动态分区裁剪 + +- 在静态分区裁剪基础上,增加动态分区裁剪功能。 +- 能够针对绑定变量查询,子查询以及NestLoop参数化查询进行分区裁剪,进一步提升分区查询性能。 + +**相关页面**:[动态分区裁剪](../../characteristic-description/enterprise-level-features/21-dynamic-partition-pruning.md) + +### 2.5 Copy导入优化 + +- 利用CPU SSE4.2指令集,在COPY导入阶段利用SIMD特性提升COPY导入的性能。 + +**相关页面**:[COPY导入优化](../../characteristic-description/enterprise-level-features/20-copy-import-optimization.md) + +### 2.6 SQL运行状态观测 + +- 对Session级别SQL运行状态进行收集执行计划树并动态采样执行算子。 +- 显著提升用户在进行慢SQL查询性能问题定位时的效率。 + +**相关页面**:[SQL运行状态观测](../../characteristic-description/enterprise-level-features/22-sql-running-status-observation.md) + +### 2.7 Brin Index + +- 数据块范围索引,相比于精准的BTREE索引,BRIN INDEX提供了一个以较小空间消耗获得一个相对较快查询速度的平衡。该索引适用于数据与物理位置相关的列,具有创建索引快,占用空间小以及顺序扫描较快等优势。 +- 该特性兼容PostgreSQL 。 + +**相关页面**:[BRIN索引](../../characteristic-description/enterprise-level-features/24-brin-index.md) + +### 2.8 Bloom Index + +- Bloom索引是基于Bloom Filter实现的一种索引结构。适用于表中有很多列,并且查询可能使用任意列组合的场景。对于传统的索引,如 B+-tree 在这种场景下可能需要建很多个索引来覆盖可能的查询条件,导致索引占用空间很大,且影响插入和更新的性能, 而这种场景只需要建单个Bloom 索引就可以应对。 +- 该特性兼容PostgreSQL。 + +**相关页面**:[BLOOM索引](../../characteristic-description/enterprise-level-features/25-bloom-index.md) + +### 2.9 PostGIS + +PostGis是一个空间数据库系统,能够提供空间对象、空间索引、空间操作函数和空间操作符等空间信息服务功能,可用于: + +- 大气科学、海洋科学、地质学、环境科学、交通管理等,处理和分析复杂的空间数据,并进行制图; +- 移动通信、移动定位、移动互联网; +- 城市管理、灾害响应、资源开发等方面; + +**相关页面**:[PostGIS](../../reference-guide/oracle-plugins/postgis-extension/postgis-overview.md) + +### 2.10 Oracle兼容增强 + +通过集成whale插件,兼容以下Oracle函数和Package: + +**函数** + +- INSTRB +- NLS_CHARSET_ID +- NLS_CHARSET_NAME +- NLS_LOWER +- NLS_UPPER +- ORA_HASH +- REMAINDER +- REPLACE +- SHOW +- SHOW_PARAMETER +- TO_TIMESTAMP +- TO_YMINTERVAL +- TZ_OFFSET +- NULLIF +- Ratio_to_report + +**Package** + +- dbms_lock +- dbms_job +- dbms_utility +- dbms_random +- dbms_output +- dbms_application_info +- dbms_metadata + +**相关页面**:[Oracle兼容增强](../../characteristic-description/application-development-interfaces/MogDB-Oracle-compatibility.md) + +### 2.11 MySQL兼容增强 + +通过集成dolphin插件,兼容以下MySQL语法和函数等: + +- Timestamp On Update +- SQL Mode(Strice Mode, Full group by) +- 用户锁 +- Insert函数 + +**相关页面**:[MySQL兼容增强](../../characteristic-description/application-development-interfaces/MogDB-MySQL-compatibility.md) + +### 2.12 OM故障诊断能力增强 + +通过增加收集系统信息,参数及测试结果差异化比较以及增加调试信息等过程增强故障诊断能力,进而帮助用户或调试人员更有效地进行问题定位。 + +该功能通过以下的工具增强来达成: + +- gstrace增强:通过增加模块切换(component switch)来获得更有针对性的执行路径,用于提升debug效率。 +- gs_check增强:原有的场景检查基础上,实现检测结果保存,以及对不同时间做的两个检测结果进行差异比较。 +- gs_watch:当MogDB发生故障时,使用此工具收集OS信息、日志信息以及配置文件等信息,来定位问题。 +- gs_gucquery:实现MogDB GUC值自动收集整理导出和差异比较。 + +**相关页面**:[故障诊断](../../characteristic-description/maintainability/fault-diagnosis.md) + +
+ +## 3. 修复缺陷 + +### 3.1 集成openGauss 3.0.0版本修复缺陷 + +- [I4VUXG](https://gitee.com/opengauss/openGauss-server/issues/I4VUXG?from=project-issue) 修复unlogged table 数据丢失问题 +- [I4SF5P](https://gitee.com/opengauss/openGauss-server/issues/I4SF5P?from=project-issue) release版本编译安装数据库,且dblink模块编译安装后,create extension dblink导致数据库core +- [I4S74D](https://gitee.com/opengauss/openGauss-server/issues/I4S74D?from=project-issue) 使用Jmeter工具向行存压缩表插入数据,数据量1G以上时必现失败(5/5),compresstype=2 +- [I4N81J](https://gitee.com/opengauss/openGauss-server/issues/I4N81J?from=project-issue) update/delete操作无法同步到订阅端 +- [I4YPJQ](https://gitee.com/opengauss/openGauss-server/issues/I4YPJQ?from=project-issue) Inserting varchar constant into MOT table using JDBC fails +- [I4PF6G](https://gitee.com/opengauss/openGauss-server/issues/I4PF6G?from=project-issue) 外键锁增强-2.0.0.灰度升级至2.2.0不提交,执行tpcc失败 +- [I4WPD1](https://gitee.com/opengauss/openGauss-server/issues/I4WPD1?from=project-issue) 简化安装模块获取安装包后解压openGauss-2.1.0-CentOS-64bit.tar.bz2缺少simpleinstall目录,无法执行极简安装 +- [I4L268](https://gitee.com/opengauss/openGauss-server/issues/I4L268?from=project-issue) 分区表多次truncate后,再进行vacuum freeze pg\_partition,系统表pg\_partition索引不准确 +- [I3HZJN](https://gitee.com/opengauss/openGauss-server/issues/I3HZJN?from=project-issue) copy命令DATE\_FORMAT缺少时分秒时,未按格式复制 +- [I4HUXD](https://gitee.com/opengauss/openGauss-server/issues/I4HUXD?from=project-issue) jsonb类型查询报错 +- [I4QDN9](https://gitee.com/opengauss/openGauss-server/issues/I4QDN9?from=project-issue) select 1.79E +308\*2,cume\_dist\(\) over\(order by 1.0E128\*1.2\)返回超出范围 +- [I4PAVO](https://gitee.com/opengauss/openGauss-server/issues/I4PAVO?from=project-issue) start with connect by record子查询识别失败 +- [I4UY9A](https://gitee.com/opengauss/openGauss-server/issues/I4UY9A?from=project-issue) opengauss列表分区创建default分区失败 +- [I4W3UB](https://gitee.com/opengauss/openGauss-server/issues/I4W3UB?from=project-issue) 创建并使用自定义类型创建视图,重命名该自定义类型后,无法获取视图定义 +- [I4WRMX](https://gitee.com/opengauss/openGauss-server/issues/I4WRMX?from=project-issue) 重启数据库且enable\_stmt\_track参数关闭时,查询statement\_history表记录应该无记录,实际有记录,statement\_history表的数据未清空 +- [I4WOBH](https://gitee.com/opengauss/openGauss-server/issues/I4WOBH?from=project-issue) GUC设置pagewriter\_sleep为360000后恢复默认值2000,重启库失败 + +### 3.2 MogDB 3.0.0版本修复缺陷 + +- update view在某些场景下可能导致数据库 coredump +- 二级分区表创建local索引表在某些场景下可能导致数据库coredump +- connect by语句在某些场景下可能导致数据库coredump + +
+ +## 4. 兼容性 + +本版本支持以下操作系统及CPU架构组合: + +| 操作系统 | CPU架构 | +| --------------------- | --------------------------------------------- | +| CentOS 7.x | X86_64(Intel,AMD,海光,兆芯) | +| Redhat 7.x | X86_64(Intel,AMD,海光,兆芯) | +| openEuler 20.03LTS | ARM(鲲鹏)、X86_64(Intel,AMD,海光,兆芯) | +| 银河麒麟V10 | ARM(鲲鹏)、X86_64(Intel,AMD,海光,兆芯) | +| 统信UOS V20-D / V20-E | ARM(鲲鹏)、X86_64(Intel,AMD,海光,兆芯) | +| 统信UOS V20-A | X86_64(Intel,AMD,海光,兆芯) | + +## 5. 已知问题 + +在分区表使用PBE场景下,动态分区裁剪小概率可能会导致core dump,规避方案为暂时禁用resource track,也即设置enable_resource_track=off。该参数已经纳入推荐参数设置。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.1.md b/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.1.md new file mode 100644 index 00000000..863939f5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.1.md @@ -0,0 +1,84 @@ +--- +title: MogDB 3.0.1 +summary: MogDB 3.0.1 +author: Guo Huan +date: 2022-08-04 +--- + +# MogDB 3.0.1 + +## 1. 版本说明 + +MogDB 3.0.1是MogDB 3.0.0的补丁版本,于2022.07.30发布,在MogDB 3.0.0的基础上主要进行了bug修复的工作。 + +
+ +## 2. 修复缺陷 + +### 2.1 Kernel + +- 修复动态分区裁剪在pbe场景下概率出现数据库异常的问题 +- 修复gstrace_check_dump_usess导致数据库异常的问题 +- 修复分区表达式类型转换时结果错误的问题 +- 修复集群环境下在async_submit=on时,特定情况下数据库异常的问题 +- 修复gs_dump导出使用类型创建的表时候语句错误 +- 修复gs_dump处理on update时的问题 +- 修复新会话对全局临时表执行merge操作时报无法打开表文件的问题 +- 修复opengauss_exporter和mogdb的兼容问题 +- 修复pg_get_tabledef函数不能正确获取根据type类型创建的表DDL的问题 +- 修复在表的非属主数据库中使用pg_get_tabledef函数获取分区表tablespace错误的问题 +- 修复使用package包中的exception_init函数报错的问题 +- 修复当log_min_messages = debug5 时,插入特定数据失败的问题 +- 修复二级分区表创建bloom索引后,pg_repack执行失败的问题 +- 修复mysql兼容on update timestamp memcheck测试问题 +- 修复gs_async_submit_sessions_status视图应在dbe_perf下的问题 +- 修复断开连接重连后on update timestamp特性失效的问题 +- 修复查询内存使用视图时导致的数据库异常的问题 +- 修复pg_get_tabledef没有生成on update current_timestamp语法的问题 +- 修复tools包内lib目录内缺少libcjson库依赖文件的问题 + +### 2.2 CM + +- 修改代码使DCF模式下暂不支持AZ相关的switchover操作(-a/-A/-z [az_name]) +- 修复cm_ctl设置cms升主模式为AUTO时偶尔失败的问题 +- 修复cm_agent的强制kill机制导致处于coredump状态的mogdb进程无法生成完整corefile文件的问题 + +### 2.3 插件 + +- 【whale】dbms_output包支持serveroutput +- 【whale】修复dbms_utility.db_version的参数不应该为inout +- 【whale】修复behavior_compat_options='proc_outparam_override'情况下创建插件报错的问题 +- 【whale】修复get_line 和get_lines 输出值不正确的问题 +- 【dolphin】修复insert函数插入时的越界问题 +- 【orafce】 删除orafce中与whale冲突的包与视图,函数定义增加package定义以支持在pgplsql中的调用 +- 【orafce】 修复utl_file.fopen触发了数据库core,文件名为空指针的问题 +- 【orafce】 修复表带有on update timestamp属性字段时,pg_repack重构缺失default属性的问题 +- 【wal2json】修复delete event在表仅有唯一索引时候的输出错误 + +
+ +## 3. 已知issue + +- whale插件中,to_timestamp函数无法将date类型转换为timestamp类型; + + 临时解决方案:新增一个to_timestamp函数,入参为timestamp without time zone,返回值和类型和入参一样 + + ```sql + CREATE or replace FUNCTION pg_catalog.to_timestamp(timestamp without time zone) + RETURNS timestamp without time zone + IMMUTABLE + AS $$ + select $1; + $$ LANGUAGE sql; + ``` + +- 使用for reverse.. loop循环的存储过程输出结果与Oracle表现不一致。 + + 临时解决方案: + + 1. 如果使用MTK迁移原应用代码,时会自动转换 + 2. 新写的代码需要手动对调开始值和结束值的位置 + +- 在wal_level=hot_standby模式下,gs_probackup指定的recovery-target-time大于最后一次备份集时间时进行PITR恢复会失败。 +- query_dop设置成非默认值1时,执行百万级数据量查询,执行报错:ERROR: bogus varno: 65001 +- 压缩表中tuple未按照指定的顺序进行存放,而是内部做了数据顺序的调整,导致压缩表在cluster聚簇命令之后tuple顺序不是预期的数据顺序(数据不会丢失,只是数据的存放顺序与设计预期不符)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.2.md b/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.2.md new file mode 100644 index 00000000..734e805c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/3.0.2.md @@ -0,0 +1,156 @@ +--- +title: MogDB 3.0.2 +summary: MogDB 3.0.2 +author: Guo Huan +date: 2022-09-19 +--- + +# MogDB 3.0.2 + +## 1. 版本说明 + +MogDB 3.0.2是MogDB 3.0.0的补丁版本,于2022.09.16发布,在MogDB 3.0.1的基础上主要进行了以下修改的工作。 + +
+ +## 2. 功能修改 + +- 版本升级改造:支持从v2.0直接升级到v3.0版本(中间不用再经过v2.1中转) + +- gsql '\l'命令增加显示数据库的兼容模式 + +
+ +## 3. 修复缺陷 + +- 修复开启undo_retention_time参数后,数据库频繁打印warning日志的问题 + +- 修复版本升级后,执行vacuum或analyze时找不到gs_global_chain报错的问题 + +- 修复主备流复制中,主机新建表空间中的数据不能同步到备机的问题 + +- 修复设置log_min_messages = debug5时,进行相关CREATE或SELECT操作时报错的问题 + +- 修复更新分区表字段时,会持续打印“error parameter when release fake relation”的问题 + +- 修复PTK安装数据库时,加载dolphin动态库后起库失败的问题 + +- 对x86系统中的xlog record插入进行优化 + +- 修复在短链接业务压力较高时,即使没有使用ustore表也会导致ustore zone溢出的问题 + +- 修复行级压缩导致的cluster命令之后的tuple乱序的问题 + +- 修复dolphin扩展在on update current_timestamp语法下,update varchar数据类型报function查找错误的问题 + +- 修改使vaccum中事务不使用异步提交功能 + +- 修复打开线程池导致的概率性出现hang住的问题 + +- 修复gstrace stop操作在没有新trace数据写入时会hang住的问题 + +- 修复开启并行解码后,在多事务的情况下,返回LSN错误导致重启应用后重复解析数据的问题 + +- 修复异步提交导致的概率性出现coredump的问题 + +- 修复对视图手工加行锁导致的数据库coredump + +- 修复并行回放或极致恢复在page压缩场景下导致的coredump + +- 修复主备环境下,主库频繁创建和删除database,在备库gsql连接该database导致的coredump + +- 修复drop table of type后再创建同名domain,创建pacakge使用该字段导致的coredump + +
+ +## 4. 同步openGauss 3.0.1修复 + +- 解决分区表autovacuum时已达到清理阈值但没有自动清理 + +- Fix logical decode core. + +- Fix deserialize func and view. + +- Fix gs_dump + +- Fix ustore bug in publication. + +- DFX: add exit log in PercentileMain + +- use RetryDataFileIdOpenFile to prevent the flags from being modified + +- set compressByteConvert/compressDiffConvert to true when defElem is set to true + +- bugfix: mdtruncate redo can not read compress_opt + +- bugfix: backup failed when uncompressed page in compressed table + +- fixed the bug of join (like...including reloptions) will success even if reloptions contains compresstype compresstype can be used with (semgent=off) reloption + +- bugfix: poor index compression ratio when use default pglz compression top standby repair + +- bugfix: poor index compression ratio when use default pglz compression + +- change fastcheck + +- fix partition error + +- fix record type issue caused by composite datum + +- fix create index info + +- fix generated issue + +- 修复hash_index回放时未判断返回值引发的core问题 + +- 修复SSL认证模式下中间人攻击的问题 + +- 修复array_set函数数组下界整数回绕问题 + +- 修复array_set函数数组下界整数回绕问题 + +- gs_ctl添加-C参数适配流失容灾 + +- repair opengauss close failed issue + +- repair GSC no cache issue + +- repair gs_gsc_memory_detail memory info inaccurate issue + +- repair wal_level=archive in switchover/failover get tuple concurrently updated issue + +- repair gsc sub thread exit error issue + +- solve the switchover problem of pagewriter exiting + +- solve the switchover bugs caused by the wake_sub_threads + +- [回合主线]fix bug interval分区exchange失败 + +- Fix the bug that the pgplsql invokes the syntax parser error + +- 修复发布订阅死锁问题 + +- 修复wal2json插件编译时报logical.h文件中的DefElem类型未声明的错误 + +- smp bugfix + +- 修复主备间来回切换,数据库core掉问题 + +- change log of alter compresstype\compress_chunk_size + +- optimize the message for create table + +- Reserve 160kb where backup compressed file + +
+ +## 5. 已知issue + +| 序号 | 问题描述 | 影响分析 | 规避及应急措施 | +| ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 1 | 数据库加载dolphin动态库后,进行部分SQL操作概率性导致数据库宕机并无法启动 | **风险:高(影响程度:高;发生概率:中)**
用户在加载dolphin动态库后使用部分SQL操作后会导致数据宕机并无法启动。 | **规避措施:**加载dolphin并创建dolphin扩展后,去掉加载dolphin配置并重启数据库。
**应急措施:**无 | +| 2 | 主备压测情况下,备库概率性出现coredump问题 | **风险:高(影响程度:高;发生概率:低)**
主库在频繁进行create database和drop database时,会导致备库回放数据时把invalid数据页加载到缓冲池从而产生coredump | **规避措施:**避免频繁的create database和drop database操作,可以减小发生的概率,但是不能完全避免
**应急措施:**无 | +| 3 | 主备压测情况下,备库会概率性出现某些被修改数据查不到的问题 | **风险:高(影响程度:高;发生概率:中)**
部分时候,从备库查询数据会查不到刚刚被update的数据,现象类似数据被删除 | **规避措施:**备库查询时候,设置hot_standby_feedback参数,避免需要查询的数据被主库过早回收。
**应急措施:**无 | +| 4 | 版本升级后point类型可以使用>、>=、<、<=、=等操作符,正常正常情况下,point类型不能使用这些操作符 | **风险:低(影响程度:低;发生概率:高)**
升级后,point类型对应操作符可以使用,但结果依然报错。 | **规避措施:**本类型非普通数据类型,通常不会被使用到,如果确实需要对应报错,可以手动删除类型对应的操作符元数据解决。
**应急措施:**无 | +| 5 | 升级后oracle兼容dbms_job.user_export入参非法时可以返回结果,正常情况下需要报参数非法错误 | **风险:低(影响程度:低;发生概率:高)**
升级后,arm机器测试入参非法可以返回结果。 | **规避措施:**认为属于正常现象,如果确实需要此处报错,需要重新安装oracle兼容性插件。
**应急措施:**无 | \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/release-note.md b/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/release-note.md new file mode 100644 index 00000000..cce60f12 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/mogdb-new-feature/release-note.md @@ -0,0 +1,14 @@ +--- +title: 发布说明 +summary: 发布说明 +author: Guo Huan +date: 2022-09-27 +--- + +# 发布说明 + +| 版本 | 发布日期 | 概述 | +| ------------------- | ------------- | ------------------------------------------------------------ | +| [3.0.2](./3.0.2.md) | 2022年9月16日 | MogDB 3.0.2版本是3.0.0的补丁版本,新增版本升级改造(从v2.0直接升级到v3.0版本),gsql '\l'命令增加显示数据库的兼容模式,同时修复已知缺陷,并同步openGauss 3.0.1的修复。 | +| [3.0.1](./3.0.1.md) | 2022年7月30日 | MogDB 3.0.1版本是3.0.0的补丁版本,在3.0.0的基础上主要进行了kernel、CM及插件的bug修复工作。 | +| [3.0.0](./3.0.0.md) | 2022年6月30日 | MogDB 3.0.0版本基于2.1版本进一步增强,并合入了openGauss 3.0.0版本的新增特性,如行存转向量化、并行逻辑解码、发布订阅、CM等,同时新增异步事务提交、索引创建并行控制、动态分区裁剪、Copy导入优化、SQL运行状态观测、Brin Index、Bloom Index等自研特性。 | \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/1-enhanced-opengauss-kernel.md b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/1-enhanced-opengauss-kernel.md new file mode 100644 index 00000000..ae892da7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/1-enhanced-opengauss-kernel.md @@ -0,0 +1,12 @@ +--- +title: 增强的openGauss内核 +summary: 增强的openGauss内核 +author: Liuxu +date: 2021-06-09 +--- + +# 增强的openGauss内核 + +
+ +MogDB是在openGauss开源内核的基础上封装和改善的对于企业应用更加友好的企业级数据库。在openGauss内核的基础上,MogDB增加了MogHA、时序(应对IoT场景)、分布式(实现每个数据节点为一个openGauss内核的分布式环境)、Oracle视图兼容(DBA_和V$视图)等多种插件,其中MogHA插件用于进行主备架构下高可用的自动化管理,对于企业级应用来说是至关重要的。同时也同步研发了MogDB Manager管理软件,其中包括备份恢复、性能监控,健康检查工具包、自动化部署、数据库迁移、数据同步、兼容性分析、性能压测和极限数据恢复多种针对企业级易用性需求的组件。 diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/2-docker-based-mogdb.md b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/2-docker-based-mogdb.md new file mode 100644 index 00000000..b4118a66 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/2-docker-based-mogdb.md @@ -0,0 +1,37 @@ +--- +title: 容器版本的MogDB +summary: 容器版本的MogDB +author: Liuxu +date: 2021-06-09 +--- + +# 容器版本的MogDB + +
+ +## 特点 + +- 随着每一个MogDB的版本变化,第一时间发布镜像的新版本。 +- 容器版本数据库镜像内置最佳实践的初始化参数配置。 +- 容器版本数据库同时支持x86平台和ARM平台。 +- MogDB 2.1容器版支持最新版的compat-tools和插件功能。 + +**目前已经支持x86-64和ARM64两种架构,请根据您宿主机的机器架构获取对应的容器镜像。** + +从2.0版本开始(包括2.0版本) + +- x86-64架构的MogDB运行在[Ubuntu 18.04操作系统](https://ubuntu.com/)中 +- ARM64架构的MogDB运行在[Debian 10 操作系统](https://www.debian.org/)中 + +在1.1.0版本之前(包括1.1.0版本) + +- x86-64架构的MogDB运行在[CentOS 7.6操作系统](https://www.centos.org/)中 +- ARM64架构的MogDB运行在[openEuler 20.03 LTS操作系统](https://openeuler.org/zh/)中 + +
+ +## 如何使用本镜像 + +您可以从下方获取容器版本的详细内容: + +[安装指南-容器化安装](../../installation-guide/docker-installation/docker-installation.md) diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/5-wal2json-extention-for-mogdb&opengauss.md b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/5-wal2json-extention-for-mogdb&opengauss.md new file mode 100644 index 00000000..37efeea0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/5-wal2json-extention-for-mogdb&opengauss.md @@ -0,0 +1,125 @@ +--- +title: wal2json extention for MogDB&openGauss +summary: wal2json extention for MogDB&openGauss +author: Guo Huan +date: 2021-06-02 +--- + +# wal2json extention for MogDB&openGauss + +## 组件获取 + + + +
+ +## 逻辑解码(wal2json) + +基于MogDB和openGauss的wal2json插件,可以将逻辑日志文件输出为JSON格式供您查看。 + +
+ +## 前提条件 + +已设置实例参数wal_level = logical。 + +
+ +## 背景信息 + +wal2json是逻辑解码插件,使用该插件可以访问由INSERT和UPDATE生成的元组,解析WAL中的内容。 + +wal2json插件会在每个事务中生成一个JSON对象。JSON对象中提供了所有新/旧元组,额外选项还可以包括事务时间戳、限定架构、数据类型、事务ID等属性。 + +
+ +## 通过SQL获取JSON对象 + +1. 登录MogDB数据库 + +2. 执行如下命令建表及初始化插件。 + + ```sql + --开另一个session执行以下 + pg_recvlogical -d mogdb --slot test_slot --create-slot -P wal2json + pg_recvlogical -d mogdb --slot test_slot --start -o pretty-print=1 -f - + --进行一些基本的DML操作 + CREATE TABLE test_table ( + id char(10) NOT NULL, + code char(10), + PRIMARY KEY (id) + ); + MogDB=# INSERT INTO test_table (id, code) VALUES('id1', 'code1'); + INSERT 0 1 + MogDB=# update test_table set code='code2' where id='id1'; + UPDATE 1 + MogDB=# delete from test_table where id='id1'; + DELETE 1 + ``` + + 对应DML的输出: + + **INSERT** + + ```json + { + "change": [ + { + "kind": "insert", + "schema": "mdmv2", + "table": "test_table", + "columnnames": ["id", "code"], + "columntypes": ["character(10)", "character(10)"], + "columnvalues": ["id1 ", "code1 "] + } + ] + } + ``` + + **UPDATE** + + ```json + { + "change": [ + { + "kind": "update", + "schema": "mdmv2", + "table": "test_table", + "columnnames": ["id", "code"], + "columntypes": ["character(10)", "character(10)"], + "columnvalues": ["id1 ", "code2 "], + "oldkeys": { + "keynames": ["id"], + "keytypes": ["character(10)"], + "keyvalues": ["id1 "] + } + } + ] + } + ``` + + **DELETE** + + ```json + { + "change": [ + { + "kind": "delete", + "schema": "mdmv2", + "table": "test_table", + "oldkeys": { + "keynames": ["id"], + "keytypes": ["character(10)"], + "keyvalues": ["id1 "] + } + } + ] + } + ``` + + 也可以用REPLICA IDENTITY来决定对表UPDATE和DELETE操作时,logical日志输出信息的详细程度。 + + - DEFAULT:逻辑日志中包含表中主键列被UPDATE或DELETE的前值的信息。 + - NOTHING:逻辑日志中不包含表中任何UPDATE或DELETE变更的信息。 + - FULL:逻辑日志中包含表中被UPDATE或DELETE列的前值的整行信息。 + - USING INDEX :仅包含指定索引中所有列的前值信息。 diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/DBMS-RANDOM.md b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/DBMS-RANDOM.md new file mode 100644 index 00000000..da1ec2a2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/DBMS-RANDOM.md @@ -0,0 +1,532 @@ +--- +title: DBMS_RANDOM随机函数包:在MogDB数据库中生成随机数(数字、字符串和日期) +summary: DBMS_RANDOM随机函数包:在MogDB数据库中生成随机数(数字、字符串和日期) +author: Liu Xu +date: 2021-09-06 +--- + +# DBMS_RANDOM随机函数包 :在MogDB数据库中生成随机数(数字、字符串和日期) + +
+ +## compat-tools介绍 + +compat-tools是一个兼容工具集合,旨在为从其他异构数据库,迁移到 MogDB之后的系统,创建必要的函数,以及系统视图的兼容。为后续的系统运维与应用改造提供便利。 + +
+ +## 获取compat-tools + +若要安装 compat-tools,请从[https://gitee.com/enmotech/compat-tools](https://gitee.com/enmotech/compat-tools)下载中心下载该工具的最新版本。 + +
+ +## compat-tools功能 + +1. runMe.sql: 总调度脚本 +2. Oracle_Views.sql: 兼容Oracle数据库数据字典及视图 +3. Oracle_Functions.sql: 兼容Oracle数据库函数 +4. Oracle_Packages.sql: 兼容Oracle数据库管理包 +5. MySQL_Views.sql: 兼容MySQL数据库数据字典及视图 //TODO +6. MySQL_Functions.sql: 兼容MySQL数据库函数 //TODO + +
+ +## compat-tools支持的数据库版本 + +- MogDB 2.0 +- MogDB 1.1 + +
+ +## 安装和使用compat-tools的方法 + +1. 获取compat-tools: + +2. 将下载的文件存放到自定义的目录中(本文以**/opt/compat-tools-0902**为例) + + ```bash + [root@mogdb-kernel-0005 compat-tools-0902]# pwd + /opt/compat-tools-0902 + [root@mogdb-kernel-0005 compat-tools-0902]# ls -l + total 228 + -rw-r--r-- 1 root root 9592 Sep 2 14:40 LICENSE + -rw-r--r-- 1 root root 0 Sep 2 14:40 MySQL_Functions.sql + -rw-r--r-- 1 root root 0 Sep 2 14:40 MySQL_Views.sql + -rw-r--r-- 1 root root 41652 Sep 2 14:40 Oracle_Functions.sql + -rw-r--r-- 1 root root 34852 Sep 2 14:40 Oracle_Packages.sql + -rw-r--r-- 1 root root 125799 Sep 2 14:40 Oracle_Views.sql + -rw-r--r-- 1 root root 4708 Sep 2 14:40 README.md + -rw-r--r-- 1 root root 420 Sep 2 14:40 runMe.sql + ``` + +3. 切换到omm用户 + + ``` + su - omm + ``` + +4. 用omm用户执行以下脚本(26000是数据库所在的端口号) + + ```bash + gsql -d mogdb -p 26000 -f /opt/compat-tools-0902/runMe.sql + ``` + +
+ +## 开始测试DBMS_RANDOM随机函数包 + +### 登录到mogdb数据库 + +```sql +[omm@mogdb-kernel-0005 ~]$ gsql -d mogdb -p 26000 +gsql ((MogDB x.x.x build 56189e20) compiled at 2022-01-07 18:47:53 commit 0 last mr ) +Non-SSL connection (SSL connection is recommended when requiring high-security) +Type "help" for help. + +MogDB=# +``` + +
+ +- [SEED](#seed) +- [VALUE](#value) +- [STRING](#string) +- [NORMAL](#normal) +- [RANDOM](#random) +- [Generating Random Dates](#generating-random-dates) +- [Generating Random Data](#generating-random-data) + +
+ +## SEED + +**SEED**可以用来指定伪随机数生成器的种子,增加其随机性。seed可支持二进制整数,也支持长度最大为2000的字符串。如果要始终生成相同的伪随机数集,请始终使用相同的随机数种子。 + +```sql +declare +BEGIN + DBMS_OUTPUT.put_line('Run 1 : seed=0'); + DBMS_RANDOM.seed (val => 0); + FOR i IN 1 ..5 LOOP + DBMS_OUTPUT.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10)); + END LOOP; + + DBMS_OUTPUT.put_line('Run 2 : seed=0'); + DBMS_RANDOM.seed (val => 0); + FOR i IN 1 ..5 LOOP + DBMS_OUTPUT.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10)); + END LOOP; + +END; +/ +NOTICE: Run 1 : seed=0 +CONTEXT: SQL statement "CALL dbms_output.put_line('Run 1 : seed=0')" +PL/pgSQL function inline_code_block line 3 at PERFORM +NOTICE: i=1 : value=2.53745232429355 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: i=2 : value=7.749117821455 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: i=3 : value=1.86734489817172 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: i=4 : value=8.83418704243377 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: i=5 : value=6.19573155790567 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: Run 2 : seed=0 +CONTEXT: SQL statement "CALL dbms_output.put_line('Run 2 : seed=0')" +PL/pgSQL function inline_code_block line 9 at PERFORM +NOTICE: i=1 : value=2.53745232429355 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 12 at PERFORM +NOTICE: i=2 : value=7.749117821455 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 12 at PERFORM +NOTICE: i=3 : value=1.86734489817172 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 12 at PERFORM +NOTICE: i=4 : value=8.83418704243377 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 12 at PERFORM +NOTICE: i=5 : value=6.19573155790567 +CONTEXT: SQL statement "CALL dbms_output.put_line('i=' || i || ' : value=' || DBMS_RANDOM.value(low => 1, high => 10))" +PL/pgSQL function inline_code_block line 12 at PERFORM +ANONYMOUS BLOCK EXECUTE +MogDB=# +``` + +
+ +## VALUE + +**VALUE**函数用于生成一个指定范围的随机数。 若不指定范围,将生成一个大于等于0小于1的38位随机小数(小数点后38位) + +```sql +DECLARE +BEGIN + FOR cur_rec IN 1 ..5 LOOP + DBMS_OUTPUT.put_line('value= ' || DBMS_RANDOM.value()); + END LOOP; +END; +/ +NOTICE: value= .785799258388579 +CONTEXT: SQL statement "CALL dbms_output.put_line('value= ' || DBMS_RANDOM.value())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: value= .692194153089076 +CONTEXT: SQL statement "CALL dbms_output.put_line('value= ' || DBMS_RANDOM.value())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: value= .368766269646585 +CONTEXT: SQL statement "CALL dbms_output.put_line('value= ' || DBMS_RANDOM.value())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: value= .87390407640487 +CONTEXT: SQL statement "CALL dbms_output.put_line('value= ' || DBMS_RANDOM.value())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: value= .745095098391175 +CONTEXT: SQL statement "CALL dbms_output.put_line('value= ' || DBMS_RANDOM.value())" +PL/pgSQL function inline_code_block line 4 at PERFORM +ANONYMOUS BLOCK EXECUTE +``` + +若指定了范围,则会生成一个大于等于最小值且小于最大值的随机数,同时小数点后的取值限制在最大值范围内。 + +```sql +declare +BEGIN + FOR cur_rec IN 1 ..5 LOOP + DBMS_OUTPUT.put_line('value(1,100)= ' || DBMS_RANDOM.value(1,100)); + END LOOP; +END; +/ + +NOTICE: value(1,100)= 45.158544998616 +CONTEXT: SQL statement "CALL dbms_output.put_line('value(1,100)= ' || DBMS_RANDOM.value(1,100))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: value(1,100)= 36.0190920610912 +CONTEXT: SQL statement "CALL dbms_output.put_line('value(1,100)= ' || DBMS_RANDOM.value(1,100))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: value(1,100)= 73.5194435422309 +CONTEXT: SQL statement "CALL dbms_output.put_line('value(1,100)= ' || DBMS_RANDOM.value(1,100))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: value(1,100)= 26.7619780991226 +CONTEXT: SQL statement "CALL dbms_output.put_line('value(1,100)= ' || DBMS_RANDOM.value(1,100))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: value(1,100)= 40.035083710216 +CONTEXT: SQL statement "CALL dbms_output.put_line('value(1,100)= ' || DBMS_RANDOM.value(1,100))" +PL/pgSQL function inline_code_block line 4 at PERFORM +ANONYMOUS BLOCK EXECUTE +MogDB=# +``` + +可按要求使用**TRUNC**或者**ROUND**改变随机数位数。例如,要生成1到10之间的随机整数,将小数点后的值舍去并给最大值加1。 + +```sql +MogDB=# select TRUNC(DBMS_RANDOM.value(1,11)) ; + + trunc +------- + + 6 + +(1 row) + +MogDB=# +``` + +
+ +## STRING + +**STRING** 函数返回指定长度的随机字符串。`OPT` 参数定义了字符串的类型。 详细如下: + +- 'u', 'U' - 返回一个由大写字母组成的字符串 +- 'l', 'L' - 返回一个由小写字母组成的字符串 +- 'a', 'A' - 返回一个由大写字母和小写字母组成的字符串 +- 'x', 'X' - 返回一个由大写字母和数字组成的字符串 +- 'p', 'P' - 返回一个由任意的可打印字符组成的字符串 + +`LEN`参数定义了返回字符串的长度。 + +```sql +declare +BEGIN + FOR i IN 1 .. 5 LOOP + DBMS_OUTPUT.put_line('string(''x'',10)= ' || DBMS_RANDOM.string('x',10)); + END LOOP; +END; +/ + +NOTICE: string('x',10)= i5S6XOZxrA +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''x'',10)= ' || DBMS_RANDOM.string('x',10))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: string('x',10)= HGvRm75w19 +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''x'',10)= ' || DBMS_RANDOM.string('x',10))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: string('x',10)= N9WsQGJl6l +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''x'',10)= ' || DBMS_RANDOM.string('x',10))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: string('x',10)= hDlPevVgRb +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''x'',10)= ' || DBMS_RANDOM.string('x',10))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: string('x',10)= ZdSd8x8RKx +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''x'',10)= ' || DBMS_RANDOM.string('x',10))" +PL/pgSQL function inline_code_block line 4 at PERFORM +ANONYMOUS BLOCK EXECUTE +MogDB=# +``` + +**STRING**和**VALUE**函数结合可以生成各种长度的字符串。 + +```sql +declare +BEGIN + FOR i IN 1 .. 5 LOOP + DBMS_OUTPUT.put_line('string(''L'',?)= ' || DBMS_RANDOM.string('L',TRUNC(DBMS_RANDOM.value(10,21)))); + END LOOP; +END; +/ + +NOTICE: string('L',?)= kcyzowdxqbyzu +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''L'',?)= ' || DBMS_RANDOM.string('L',TRUNC(DBMS_RANDOM.value(10,21))))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: string('L',?)= ohzpljyatsplqtbbus +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''L'',?)= ' || DBMS_RANDOM.string('L',TRUNC(DBMS_RANDOM.value(10,21))))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: string('L',?)= hbrjsfeevoi +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''L'',?)= ' || DBMS_RANDOM.string('L',TRUNC(DBMS_RANDOM.value(10,21))))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: string('L',?)= lfsapmytdamvwcw +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''L'',?)= ' || DBMS_RANDOM.string('L',TRUNC(DBMS_RANDOM.value(10,21))))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: string('L',?)= pcvtxnwzomkqwpfzes +CONTEXT: SQL statement "CALL dbms_output.put_line('string(''L'',?)= ' || DBMS_RANDOM.string('L',TRUNC(DBMS_RANDOM.value(10,21))))" +PL/pgSQL function inline_code_block line 4 at PERFORM +ANONYMOUS BLOCK EXECUTE +MogDB=# +``` + +
+ +## NORMAL + +NORMAL函数返回一组随机数。 + +```sql +declare +BEGIN + FOR cur_rec IN 1 ..5 LOOP + DBMS_OUTPUT.put_line('normal= ' || DBMS_RANDOM.normal()); + END LOOP; +END; +/ + +NOTICE: normal= .838851847718988 +CONTEXT: SQL statement "CALL dbms_output.put_line('normal= ' || DBMS_RANDOM.normal())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: normal= -.523612260373397 +CONTEXT: SQL statement "CALL dbms_output.put_line('normal= ' || DBMS_RANDOM.normal())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: normal= -.241931681458075 +CONTEXT: SQL statement "CALL dbms_output.put_line('normal= ' || DBMS_RANDOM.normal())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: normal= -.120847761874286 +CONTEXT: SQL statement "CALL dbms_output.put_line('normal= ' || DBMS_RANDOM.normal())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: normal= .360125112757284 +CONTEXT: SQL statement "CALL dbms_output.put_line('normal= ' || DBMS_RANDOM.normal())" +PL/pgSQL function inline_code_block line 4 at PERFORM +ANONYMOUS BLOCK EXECUTE +MogDB=# +``` + +
+ +## RANDOM + +```sql +declare +BEGIN + FOR i IN 1 .. 5 LOOP + DBMS_OUTPUT.put_line('random= ' || DBMS_RANDOM.random()); + END LOOP; +END; +/ +NOTICE: This function is deprecated with Release 11gR1, although currently supported, it should not be used. +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: random= -1023930867 +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: This function is deprecated with Release 11gR1, although currently supported, it should not be used. +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: random= 1068572119 +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: This function is deprecated with Release 11gR1, although currently supported, it should not be used. +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: random= 95361253 +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: This function is deprecated with Release 11gR1, although currently supported, it should not be used. +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: random= -712638729 +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: This function is deprecated with Release 11gR1, although currently supported, it should not be used. +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: random= -1251059926 +CONTEXT: SQL statement "CALL dbms_output.put_line('random= ' || DBMS_RANDOM.random())" +PL/pgSQL function inline_code_block line 4 at PERFORM +ANONYMOUS BLOCK EXECUTE +MogDB=# +``` + +
+ +## Generating Random Dates + +目前没有生成随机日期的特定函数,但是可以为现有日期添加随机数来产生随机日期。下面的示例为生成下一年的随机日期。 + +```sql +declare +BEGIN + FOR i IN 1 .. 5 LOOP + DBMS_OUTPUT.put_line('date= ' || TRUNC(SYSDATE + DBMS_RANDOM.value(0,366))); + END LOOP; +END; +/ + +NOTICE: date= 2021-10-06 00:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('date= ' || TRUNC(SYSDATE + DBMS_RANDOM.value(0,366)))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: date= 2022-05-09 00:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('date= ' || TRUNC(SYSDATE + DBMS_RANDOM.value(0,366)))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: date= 2022-04-07 00:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('date= ' || TRUNC(SYSDATE + DBMS_RANDOM.value(0,366)))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: date= 2021-11-29 00:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('date= ' || TRUNC(SYSDATE + DBMS_RANDOM.value(0,366)))" +PL/pgSQL function inline_code_block line 4 at PERFORM +NOTICE: date= 2022-06-04 00:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('date= ' || TRUNC(SYSDATE + DBMS_RANDOM.value(0,366)))" +PL/pgSQL function inline_code_block line 4 at PERFORM +ANONYMOUS BLOCK EXECUTE +MogDB=# +``` + +通过进行正确除法运算,可以给日期添加小时、秒或分钟。 + +```sql +DECLARE + l_hours_in_day NUMBER := 24; + l_mins_in_day NUMBER := 24*60; + l_secs_in_day NUMBER := 24*60*60; +BEGIN + FOR i IN 1 .. 5 LOOP + DBMS_OUTPUT.put_line('hours= ' || (TRUNC(SYSDATE) + (TRUNC(DBMS_RANDOM.value(0,1000))/l_hours_in_day))); + END LOOP; + FOR i IN 1 .. 5 LOOP + DBMS_OUTPUT.put_line('mins = ' || (TRUNC(SYSDATE) + (TRUNC(DBMS_RANDOM.value(0,1000))/l_mins_in_day))); + END LOOP; + FOR i IN 1 .. 5 LOOP + DBMS_OUTPUT.put_line('secs = ' || (TRUNC(SYSDATE) + (TRUNC(DBMS_RANDOM.value(0,1000))/l_secs_in_day))); + END LOOP; +END; +/ +NOTICE: hours= 2021-10-13 22:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('hours= ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_hours_in_day)))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: hours= 2021-10-10 00:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('hours= ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_hours_in_day)))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: hours= 2021-09-07 02:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('hours= ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_hours_in_day)))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: hours= 2021-09-26 11:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('hours= ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_hours_in_day)))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: hours= 2021-09-19 22:00:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('hours= ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_hours_in_day)))" +PL/pgSQL function inline_code_block line 6 at PERFORM +NOTICE: mins = 2021-09-04 00:01:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('mins = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_mins_in_day)))" +PL/pgSQL function inline_code_block line 9 at PERFORM +NOTICE: mins = 2021-09-04 11:56:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('mins = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_mins_in_day)))" +PL/pgSQL function inline_code_block line 9 at PERFORM +NOTICE: mins = 2021-09-04 00:53:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('mins = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_mins_in_day)))" +PL/pgSQL function inline_code_block line 9 at PERFORM +NOTICE: mins = 2021-09-04 00:21:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('mins = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_mins_in_day)))" +PL/pgSQL function inline_code_block line 9 at PERFORM +NOTICE: mins = 2021-09-04 12:38:00 +CONTEXT: SQL statement "CALL dbms_output.put_line('mins = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_mins_in_day)))" +PL/pgSQL function inline_code_block line 9 at PERFORM +NOTICE: secs = 2021-09-04 00:10:28 +CONTEXT: SQL statement "CALL dbms_output.put_line('secs = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_secs_in_day)))" +PL/pgSQL function inline_code_block line 12 at PERFORM +NOTICE: secs = 2021-09-04 00:15:31 +CONTEXT: SQL statement "CALL dbms_output.put_line('secs = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_secs_in_day)))" +PL/pgSQL function inline_code_block line 12 at PERFORM +NOTICE: secs = 2021-09-04 00:09:07 +CONTEXT: SQL statement "CALL dbms_output.put_line('secs = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_secs_in_day)))" +PL/pgSQL function inline_code_block line 12 at PERFORM +NOTICE: secs = 2021-09-04 00:06:54 +CONTEXT: SQL statement "CALL dbms_output.put_line('secs = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_secs_in_day)))" +PL/pgSQL function inline_code_block line 12 at PERFORM +NOTICE: secs = 2021-09-04 00:06:32 +CONTEXT: SQL statement "CALL dbms_output.put_line('secs = ' || (TRUNC(SYSDATE)+ (TRUNC(DBMS_RANDOM.value(0,1000))/l_secs_in_day)))" +PL/pgSQL function inline_code_block line 12 at PERFORM +ANONYMOUS BLOCK EXECUTE +MogDB=# +``` + +
+ +## Generating Random Data + +DBMS_RANDOM 包用于生成随机测试数据。通过将其与查询结合,可以快速生成大量数据。 + +```sql +MogDB=# CREATE TABLE random_data ( + id NUMBER, + small_number NUMBER(5), + big_number NUMBER, + short_string VARCHAR2(50), + long_string VARCHAR2(400), + created_date DATE, + CONSTRAINT random_data_pk PRIMARY KEY (id) +); +NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index "random_data_pk" for table "random_data" +CREATE TABLE +MogDB=# +``` + +```sql +MogDB=# INSERT INTO random_data +SELECT generate_series(1,29999), + TRUNC(DBMS_RANDOM.value(1,5)) AS small_number, + TRUNC(DBMS_RANDOM.value(100,10000)) AS big_number, + DBMS_RANDOM.string('L',TRUNC(DBMS_RANDOM.value(10,50))) AS short_string, + DBMS_RANDOM.string('L',TRUNC(DBMS_RANDOM.value(100,400))) AS long_string, + TRUNC(SYSDATE + DBMS_RANDOM.value(0,366)) AS created_date; +INSERT 0 29999 +MogDB=# +MogDB=# select count(*) from random_data; + count +------- + 29999 +(1 row) + +MogDB=# +``` diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/compat-tools.md b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/compat-tools.md new file mode 100644 index 00000000..47608323 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/compat-tools.md @@ -0,0 +1,18 @@ +--- +title: compat-tools +summary: compat-tools +author: Zhang Cuiping +date: 2021-07-14 +--- + +# compat-tools + +本项目是一个兼容工具集合,旨在为从其他异构数据库,迁移到 MogDB 之后的系统,创建必要的函数,以及系统视图的兼容。为后续的系统运维与应用改造提供便利。 + +脚本中带有版本控制,直接运行脚本时,会根据如下三种情况进行处理: + +1. 若待创建对象在目标数据库中不存在,则直接进行创建 +2. 若待创建对象版本高于目标数据库中的对象版本,则进行升级重建 +3. 若待创建对象版本不高于目标数据库中的对象版本,则跳过创建 + +组件获取及使用方法详见[compat-tools仓库页面](https://gitee.com/enmotech/compat-tools)。 diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mog_filedump.md b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mog_filedump.md new file mode 100644 index 00000000..d9f32a4d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mog_filedump.md @@ -0,0 +1,106 @@ +--- +title: mog_filedump使用说明 +summary: mog_filedump使用说明 +author: Guo Huan +date: 2021-11-15 +--- + + + +# mog_filedump使用说明 + +## 简介 + +mog_filedump是根据pg_filedump工具改进兼容性,移植到MogDB上的解析数据文件工具,用于将MogDB的heap/index/control文件转换成用户可读的格式内容。本工具能够根据需要,解析数据列中一部分字段,也能直接以二进制格式转储数据内容。该工具可以通过文件中块的数据,自动确定文件的类型。要格式化pg_control文件必须使用-c选项。 + +
+ +## 原理说明 + +实现步骤主要分三步: + +1. 读取数据文件中的数据块。 + +2. 以对应数据类型的回调函数,解析对应类型的数据。 + +3. 调用对应的数据类型函数输出,打印数据内容。 + +
+ +## 恩墨的改进 + +1. 对MogDB做了兼容性移植。 + +2. 修复官方bug:数据类型char的解析bug。 + +3. 修复官方bug:在多字段场景下,解析数据文件,数据类型name会产生数据长度不对齐bug。 + +
+ +## 安装方法 + +访问[MogDB官网下载页面](https://www.mogdb.io/downloads/mogdb)下载对应版本的工具包,将工具放在MogDB安装路径的bin目录下即可。如下图所示,toolkits-xxxxxx.tar.gz即为包含mog_filedump的工具包。 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/about-mogdb/open-source-components-3.png) + +
+ +## 使用方法 + +``` +mog_filedump [-abcdfhikxy] [-R startblock [endblock]] [-D attrlist] [-S blocksize] [-s segsize] [-n segnumber] file +``` + +对heap和index文件有效的选项如下: + +| 选项 | 功能 | +| ---- | ------------------------------------------------------------ | +| -a | 显示绝对路径 | +| -b | 输出一个范围的二进制block images | +| -d | 输出文件块内容 | +| -D | 表的数据类型。
目前支持的数据类型有:bigint、bigserial、bool、charN、date、float、float4、float8、int、json、macaddr、name、oid、real、serial、smallint、smallserial、text、time、timestamp、timetz、uuid、varchar、varcharN、xid、xml、~。
'~'表示忽略后面所有的数据类型,比如元组有10列,`-D 前三列数据类型, ~`表示只解析该表元组前三列数据。 | +| -f | 输出并解析数据块的内容 | +| -h | 显示使用说明和帮助信息 | +| -i | 输出并解析item的详细信息(其中包含XMIN、XMAX、Block Id、linp Index、Attributes、Size、infomask) | +| -k | 核实数据块的校验和 | +| -R | 解析并输出指定LSN范围的数据文件内容,例如 -R startblock [endblock]。如果只有startblock没有endblock,则只输出单个数据块内容 | +| -s | 设置segment大小 | +| -n | 设置segment数量 | +| -S | 设置数据块大小 | +| -x | 把块items当作索引item格式解析并输出(默认自带) | +| -y | 把块items当作堆item格式解析并输出(默认自带) | + +对控制文件有效的选项如下: + +| 选项 | 功能 | +| ---- | ------------------------ | +| -c | 解析控制文件的列表目录 | +| -f | 输出并解析数据块的内容 | +| -S | 设置控制文件解析的块大小 | + +可以结合-i和-f参数,得到更有效的数据以帮助运维人员分析与参考。 + +
+ +## 示例 + +test表基本上覆盖了mog_filedump所包含的数据类型。 + +此处是展示数据解析功能的用例,其它参数请根据实际具体需要添加使用。 + +```sql +-- 创建表test: +create table test(serial serial, smallserial smallserial, bigserial bigserial, bigint bigint, bool bool, char char(3), date date, float float, float4 float4, float8 float8, int int, json json, macaddr macaddr, name name, oid oid, real real, smallint smallint, text text, time time, timestamp timestamp, timetz timetz, uuid uuid, varchar varchar(20), xid xid, xml xml); + +-- 插入数据: +insert into test(bigint, bool, char, date, float, float4, float8, int, json, macaddr, name, oid, real, smallint, text, time, timestamp, timetz, uuid, varchar, xid, xml) values(123456789, true, 'abc', '2021-4-02 16:45:00', 3.1415926, 3.1415926, 3.14159269828412, 123456789, '{"a":1, "b":2, "c":3}'::json, '04-6C-59-99-AF-07', 'lvhui', 828243, 3.1415926, 12345, 'text', '2021-04-02 16:48:23', '2021-04-02 16:48:23', '2021-04-02 16:48:23', 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11', 'adsfghkjlzc', '9973::xid', 'Book0001'); + +-- 查询表test的数据文件所在目录。该处gs_initdb指定的数据目录为db_p。所以表test数据文件在db_p/base/15098/32904 +postgres=# select pg_relation_filepath('test'); +base/15098/32904 (1 row) + +-- 用mog_filedump工具解析数据文件内容: +./mog_filedump -D serial,smallserial,bigserial,bigint,bool,charN,date,float,float4,float8,int,json,macaddr,name,oid,real,smallint,text,time,timestamp,timetz,uuid,varchar,xid,xml db_p/base/15098/32904 +``` + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/reference-guide/mog_filedump.png) diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mog_xlogdump.md b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mog_xlogdump.md new file mode 100644 index 00000000..42e125c0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mog_xlogdump.md @@ -0,0 +1,305 @@ +--- +title: mog_xlogdump使用说明 +summary: mog_xlogdump使用说明 +author: Guo Huan +date: 2021-11-15 +--- + +# mog_xlogdump使用说明 + +## 简介 + +mog_xlogdump是云和恩墨独立开发的wal日志离线解析工具。主要用于在主备集群场景中,数据库永久性宕机且无法恢复的情况下,反向解析无法启动的数据库,然后在集群中恢复wal日志尾部没有同步的数据。 + +
+ +## 研发背景 + +在MogDB主备高可用集群一主多备,使用异步逻辑复制场景中,当主库宕机其事务提交完时,该事务操作的数据已经被写入wal日志中。主库宕机后由于无法发送给备库,备库会产生不完整的数据段日志。因此在主库宕机后,备库与主库之间的数据存在数据丢失、逻辑没有对齐的情况。所以其后备库组成的主备集群和实际业务中数据存在数据丢失的风险。 + +在主库恢复期间,后备库组成的集群会有业务数据写入,此时即时主库恢复,主库的wal日志末尾不完整的数据段的段号、起始和结束位置与备库中已经产生不一致现象,也会导致主库最后宕机时丢失的数据无法恢复到备库中。 + +
+ +## 使用场景 + +MogDB高可用集群中,当主库宕机时,在walbuffer写满一定比例时,或者checkpoint,或者commit时,触发walbuffer写入wal日志。由于数据库宕机,逻辑同步的WalSender线程停止发送日志,备库接收到不完整的数据段wal日志。此时则需要用flashback工具读取主库的wal日志中的数据块,并解码出对应数据操作的SQL语句,供DBA分析数据是否有价值,并恢复到备库中。 + +
+ +## 原理说明 + +该工具使用的两个机制,一个是wal日志的头部解析,另一个是逻辑复制机制。 + +实现步骤主要分三步: + +1. 读取wal日志文件,解析头部。 + +2. 依次读取数据,并反解码数据。 + +3. 根据数据不同的数据类型,回调不同类型的函数输出。 + +
+ +## 支持解析的表类型 + +目前支持分区表和普通表。 + +
+ +## 支持解析的数据类型 + +bool、bytea、char、name、int8、int2、int、text、oid、tid、xid、cid、xid32、clob、float4、float8、money、inet、varchar、numeric、int4; + +> 注意:由于mog_xlogdump是离线wal解析工具,所以暂时不支持需要用toast数据的大数据类型(clob等),下个版本将会支持toast表文件离线解析功能。 + +
+ +## 安装方法 + +访问[MogDB官网下载页面](https://www.mogdb.io/downloads/mogdb)下载对应版本的工具包,将工具放在MogDB安装路径的bin目录下即可。如下图所示,toolkits-xxxxxx.tar.gz即为包含mog_xlogdump的工具包。 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/about-mogdb/open-source-components-3.png) + +
+ +## 使用说明 + +mog_xlogdump是用于解析并显示MogDB 2.1及之后版本的Wal日志的工具。旨在帮助DBA分析与Debugging数据库问题的辅助工具。 + +mog_xlogdump解析工具暂时不支持列存表。(研究发现列存表会在cstore模式下生成两张对应的CUDesc和delta表,CUDesc是列存表的元数据,delta是列存表的临时表,是张行存表,这两张表(CUDesc,delta)都会写在wal日志中,虽然wal日志能解析出对应的delta表,但该表受表属性阈值deltarow_threshold控制 ,默认100,即小于100条数据才会写在delta表中,大于阈值就会直接写到cu文件里) + +> 注意:列存表要写delta表,需要postgres.conf中开启参数enable_delta_store = on。 + +
+ +## 使用方式 + +``` +mog_xlogdump [OPTION]... [STARTSEG [ENDSEG]] +``` + +
+ +## 选项说明 + +- -b, --bkp-details + + 输出文件块的详细信息。(默认显示block的id、rel、fork、blk、lastlsn,该参数会显示Block Image) + +- -B, --bytea_output + + 指定bytea类型解码输出的显示格式,有二进制和字符两种格式 + +- -c --connectinfo + + 指定链接字符串URL,例如`postgres://user:password@ip:port/dbname` + +- -e, --end=RECPTR + + 指定解析wal日志的结束位置,LSN号 + +- -f, --follow + + 表示当指定的wal日志解析到结尾时,继续往下一个文件解析 + +- -n, --limit=N + + 指定输出数据记录的条数 + +- -o, --oid=OID + + 指定反解码表的OID + +- -p, --path=PATH + + 指定wal日志存放目录 + +- -R, --Rel=Relation + + 指定反解码表的数据类型 + +- -r, --rmgr=RMGR + + 只显示资源管理器生成的记录内容 + +- -s, --start=RECPTR + + 指定解析wal日志的开始位置,LSN号 + +- -T, --CTimeZone_ENV + + 指定时域,默认的是UTC。 + +- -t, --timeline=TLI + + 指定开始读取wal日志的timeline + +- -V, --version + + 显示版本号 + +- -w, --write-FPW + + 显示全页写的信息,配合-b使用 + +- -x, --xid=XID + + 输出指定事务id的记录 + +- -z, --stats + + 输出插入记录的统计 + +- -v, --verbose + + 显示细节信息 + +- -?, --help + + 显示帮助信息并退出 + +
+ +## 用例一 + +### 使用场景 + +当主库宕机且无法恢复,备库可以正常链接,此时主库末发的wal日志里面可能包含有上万张表数据的操作,而mog_xlogdump工具需要根据指定的-s、-e(起始和结束的lsn位置),把所有表的数据操作都解析出来。 + +### 使用方法 + +``` +mog_xlogdump -c '备库链接串' -s '起始lsn' -e '结束lsn 主库wal日志文件 +``` + +### 解析设置 + +注:主要是为了让wal日志中记录旧数据,即update操作修改前的数据元组,和delete操作删除的数据。 + +1. 把数据库配置文件postgres.conf里的**wal_level**设置为**logical**级别。 +2. 对表进行修改: `alter table table_name replica identity full;` + +### 结果展示 + +以json格式输出wal日志数据解析结果。tuple展示格式为 `’列名’:’数据’` + +```json +{'table_name':'xxx','schema_name':'yyy','action':'insert','tuple':{'name':'xx','id':'ss'}} +``` + +### 示例 + +![fe1b12d080accfb9e54f857e79baebc](https://cdn-mogdb.enmotech.com/docs-media/mogdb/reference-guide/mog_xlogdump-1.png) + +红框中是根据解析设置后才会解析出的旧数据,如果没有设置则解析不到update和delete的旧数据。 + +其中-c后面的备机链接URL为`postgres://test:Test123456@172.16.0.44:5003/postgres` + +- postgres://为链接串标记头部 + +- test为链接用户名 + +- Test123456为链接用户的密码 + +- 172.16.0.44为备机ip地址 + +- 5003为备机链接端口 + +- postgres为链接备机的数据库名 + +- db_p/pg_xlog/000000010000000000000004为主机的wal日志文件 + +
+ +## 用例二 + +### 使用场景 + +当主库宕机且无法恢复,且备库可以正常链接,此时用户可能只关注库中的几张表(个别表),mog_xlogdump工具可以根据参数-o、-R来解析指定oid的表数据。比如-o指定表的oid,-R指定表的字段类型。 + +### 使用方法 + +创建表,写入数据并修改,用mog_xlogdump工具反解析Wal日志。 + +```sql +create table t2(id int, money money,inet inet,bool bool,numeric numeric ,text text); +insert into t2 values(1, 24.241, '192.168.255.132', true, 3.1415926, 'ljfsodfo29892ifj'); +insert into t2 values(2, 928.8271, '10.255.132.101', false, 3.1415926, 'vzvzcxwf2424@'); +update t2 set id=111, money=982.371 where id =2; +delete from t2 where id=1; + +postgres=# select * from t2; + id | money | inet | bool | numeric | text +----+---------+-----------------+------+-----------+------------------ + 1 | $24.24 | 192.168.255.132 | t | 3.1415926 | ljfsodfo29892ifj + 2 | $928.83 | 10.255.132.101 | f | 3.1415926 | vzvzcxwf2424@ +(2 rows) + +postgres=# update t2 set id=111, money=982.371 where id =2; +Postgres=# delete from t2 where id=1; +postgres=# select * from t2; + id | money | inet | bool | numeric | text +-----+-------------+----------------+------+-----------+--------------- + 111 | $982,371.00 | 10.255.132.101 | f | 3.1415926 | vzvzcxwf2424@ + +(1 rows) +``` + +### 解析设置 + +与用例一相同,设置wal_level和alter table等两个设置。 + +### 结果展示 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/reference-guide/mog_xlogdump-2.png) + +```json +./mog_xlogdump -o 16394 -R int,money,inet,bool,numeric,text ./db_p/pg_xlog/000000010000000000000004 +'insert','tuple':{'(null)':'1','(null)':'$24.24','(null)':'192.168.255.132','(null)':true,'(null)':'3.1415926','(null)':'ljfsodfo29892ifj'}} +'insert','tuple':{'(null)':'2','(null)':'$928.83','(null)':'10.255.132.101','(null)':false,'(null)':'3.1415926','(null)':'vzvzcxwf2424@'}} +'update','old_tuple':{'(null)':'2','(null)':'$928.83','(null)':'10.255.132.101','(null)':false,'(null)':'3.1415926','(null)':'vzvzcxwf2424@'},'new_tuple':{'(null)':'111','(null)':'$982,371.00','(null)':'10.255.132.101','(null)':false,'(null)':'3.1415926','(null)':'vzvzcxwf2424@'}} +'delete','tuple':{'(null)':'1','(null)':'$24.24','(null)':'192.168.255.132','(null)':true,'(null)':'3.1415926','(null)':'ljfsodfo29892ifj'}} +``` + +> 注意:由于输出格式的更改,表名、模式名和列名是依据-c链接字符串去备机上查询获取,但由于原来的-o、-R指定表oid和字段类型的方式是完全离线式,所以无法获取表名、模式名、列名这些信息,所以再用-o、-R来离线解析,不显示表名、模式名,列名显示为null。 + +``` +mog_xlogdump -o 表OID -R 表的数据类型 -s 解析起始的LSN -e 解析结束的LSN Wal日志文件 +``` + +该工具也保留了pg_xlogdump原始的功能。 + +
+ +## 用例三 + +### 使用场景 + +当用户想看wal日志头部数据内容时,或者统计wal日志一些相关信息,用mog_xlogdump原始功能。 + +### 使用方法 + +使用一(头部信息): + +``` +./mog_xlogdump -n 10 wal日志文件 +``` + +-n 10 表示只显示10条数据。 + +使用二(统计信息): + +``` +./mog_xlogdump -z wal日志文件 +``` + +### 结果展示 + +结果一 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/reference-guide/mog_xlogdump-3.png) + +结果二 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/reference-guide/mog_xlogdump-4.png) diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mogdb-monitor.md b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mogdb-monitor.md new file mode 100644 index 00000000..f701b542 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/open-source-components/mogdb-monitor.md @@ -0,0 +1,27 @@ +--- +title: mogdb-monitor +summary: mogdb-monitor +author: Guo Huan +date: 2022-04-14 +--- + +# mogdb-monitor + +mogdb-monitor是MogDB数据库集群监控部署工具,借助当前非常流行的开源监控体系prometheus框架,结合由恩墨数据库团队开发的opengauss_exporter,可以实现对MogDB数据库进行全方位的检测。 + +核心监控组件opengauss_exporter具有以下特点: + +- 支持所有版本MogDB/openGauss数据库 +- 支持监控数据库集群 +- 支持集群内主备角色判断 +- 支持自动发现数据库 +- 支持自定义查询query +- 支持在线加载配置文件 +- 支持配置线程并发数 +- 支持数据采集信息缓存 + +在grafana展示方面,云和恩墨也提供了一套完整的dashboard,既有展示每个实例详细信息的实例级dashboard,也有展示所有实例汇总信息的展示大屏,结合alertmanager组件,可以第一时间将符合规则的报警触发到相关人员。 + +
+ +组件获取及使用方法详见[mogdb-monitor仓库页面](https://gitee.com/enmotech/mogdb-monitor)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/terms-of-use.md b/product/zh/docs-mogdb/v3.1/about-mogdb/terms-of-use.md new file mode 100644 index 00000000..b7aecf04 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/terms-of-use.md @@ -0,0 +1,22 @@ +--- +title: 法律声明 +summary: 法律声明 +author: Guo Huan +date: 2021-06-01 +--- + +# 法律声明 + +**版权所有 © 2009-2022 云和恩墨(北京)信息技术有限公司。** + +您对“本文档”的复制、使用、修改及分发受知识共享(Creative Commons)署名-相同方式共享4.0国际公共许可协议(以下简称“CC BY-SA 4.0”)的约束。为了方便用户理解,您可以通过访问 了解CC BY-SA 4.0的概要(但不是替代)。CC BY-SA 4.0的完整协议内容您可以访问如下网址获取:[https://creativecommons.org/licenses/by-sa/4.0/legalcode](https://creativecommons.org/licenses/by-sa/4.0/legalcode)。 + +“本文档”部分页面内容参考自[openGauss官方文档](https://opengauss.org/zh/docs/1.1.0/docs/Quickstart/%E4%BA%86%E8%A7%A3%E4%BA%A7%E5%93%81.html)。 + +**商标声明** + +MogDB为云和恩墨(北京)信息技术有限公司的商标。本文档提及的其他所有商标或注册商标,由各自的所有人拥有。 + +**免责声明** + +本文档仅作为使用指导,除非适用法强制规定或者双方有明确书面约定,云和恩墨(北京)信息技术有限公司对本文档中的所有陈述、信息和建议不做任何明示或默示的声明或保证,包括但不限于不侵权,时效性或满足特定目的的担保。 diff --git a/product/zh/docs-mogdb/v3.1/about-mogdb/usage-limitations.md b/product/zh/docs-mogdb/v3.1/about-mogdb/usage-limitations.md new file mode 100644 index 00000000..3c03b724 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/about-mogdb/usage-limitations.md @@ -0,0 +1,27 @@ +--- +title: 使用限制 +summary: 使用限制 +author: Guo Huan +date: 2021-06-01 +--- + +# 使用限制 + +MogDB 具有如下使用限制: + +| 指标项 | 最大值 | +| ---------------------- | ---------------------------------- | +| 数据库容量 | 受限于操作系统与硬件 | +| 单表大小 | 32TB | +| 单行数据大小 | 1GB | +| 每条记录单个字段的大小 | 1GB | +| 单表记录数 | 281474976710656(2^48^) | +| 单表列数 | 250~1600(随字段类型不同会有变化) | +| 单表中的索引个数 | 无限制 | +| 复合索引包含列数 | 32 | +| 单表约束个数 | 无限制 | +| 并发连接数 | 10000 | +| 分区表的分区个数 | 1048575 | +| 分区表的单个分区大小 | 32TB | +| 分区表的单个分区记录数 | 2^55^ | +| SQL文本最大长度 | 1048576字节(1MB) | diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-1-br.md b/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-1-br.md new file mode 100644 index 00000000..4a9853f1 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-1-br.md @@ -0,0 +1,95 @@ +--- +title: 概述 +summary: 概述 +author: Liu Xu +date: 2021-03-04 +--- + +# 概述 + +数据备份是保护数据安全的重要手段之一,为了更好的保护数据安全,MogDB数据库支持三种备份恢复类型、多种备份恢复方案,备份和恢复过程中提供数据的可靠性保障机制。 + +备份与恢复类型可分为逻辑备份与恢复、物理备份与恢复、闪回恢复。 + +- 逻辑备份与恢复 + + 通过逻辑导出对数据进行备份,逻辑备份只能基于备份时刻进行数据转储,所以恢复时也只能恢复到备份时保存的数据。对于故障点和备份点之间的数据,逻辑备份无能为力,逻辑备份适合备份那些很少变化的数据,当这些数据因误操作被损坏时,可以通过逻辑备份进行快速恢复。如果通过逻辑备份进行全库恢复,通常需要重建数据库,导入备份数据来完成,对于可用性要求很高的数据库,这种恢复时间太长,通常不被采用。由于逻辑备份具有平台无关性,所以更为常见的是,逻辑备份被作为一个数据迁移及移动的主要手段。 + +- 物理备份与恢复 + + 通过物理文件拷贝的方式对数据库进行备份,以磁盘块为基本单位将数据从主机复制到备机。通过备份的数据文件及归档日志等文件,数据库可以进行完全恢复。物理备份速度快,一般被用作对数据进行备份和恢复,用于全量备份的场景。通过合理规划,可以低成本进行备份与恢复。 + +- 闪回恢复:利用回收站的闪回恢复删除的表。数据库的回收站功能类似于windows系统的回收站,将删除的表信息保存到回收站中。利用MVCC机制闪回恢复到指定时间点或者CSN点。 + +以下为MogDB支持的三类数据备份恢复方案,备份方案也决定了当异常发生时该如何恢复。 + +**表 1** 三种备份恢复类型对比 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
备份类型应用场景支持的介质工具名称恢复时间优缺点
逻辑备份与恢复适合于数据量小的场景。
可以备份单表和多表,单database和所有database。备份后的数据需要使用gsql或者gs_restore工具恢复。数据量大时,恢复需要较长时间。
磁盘
SSD
gs_dump纯文本格式数据恢复时间长。归档格式数据恢复时间中等。导出数据库相关信息的工具,用户可以自定义导出一个数据库或其中的对象(模式、表、视图等)。支持导出的数据库可以是默认数据库postgres,也可以是自定义数据库。导出的格式可选择纯文本格式或者归档格式。纯文本格式的数据只能通过gsql进行恢复,恢复时间较长。归档格式的数据只能通过gs_restore进行恢复,恢复时间较纯文本格式短。
gs_dumpall数据恢复时间长导出所有数据库相关信息工具,它可以导出MogDB数据库的所有数据,包括默认数据库postgres的数据、自定义数据库的数据、以及MogDB所有数据库公共的全局对象。只能导出纯文本格式的数据,导出的数据只能通过gsql进行恢复,恢复时间较长。
物理备份与恢复适用于数据量大的场景,主要用于全量数据备份恢复,也可对整个数据库中的WAL归档日志和运行日志进行备份。gs_backup数据量小数据恢复时间快导出数据库相关信息的OM工具,可以导出数据库参数文件和二进制文件。帮助MogDB备份、恢复重要数据、显示帮助信息和版本号信息。在进行备份时,可以选择备份内容的类型,在进行还原时,需要保证各节点备份目录中存在备份文件。在集群恢复时,通过静态配置文件中的集群信息进行恢复。只恢复参数文件恢复时间较短。
gs_basebackup恢复时可以直接拷贝替换原有的文件, 或者直接在备份的库上启动数据库,恢复时间快。对服务器数据库文件的二进制进行全量拷贝,只能对数据库某一个时间点的时间作备份。结合PITR恢复,可恢复全量备份时间点后的某一时间点。
gs_probackup恢复时可以直接恢复到某个备份点,在备份的库上启动数据库,恢复时间快。gs_probackup是一个用于管理MogDB数据库备份和恢复的工具。它对MogDB实例进行定期备份。可用于备份单机数据库或者集群主节点数据库,为物理备份。 可备份外部目录的内容,如脚本文件、配置文件、日志文件、dump文件等。 支持增量备份、定期备份和远程备份。增量备份时间相对于全量备份时间比较短,只需要备份修改的文件。当前默认备份是数据目录,如果表空间不在数据目录,需要手动指定备份的表空间目录进行备份。当前只支持在主机上执行备份。
闪回恢复适用于:
1)误删除表的场景;
2)需要将表中的数据恢复到指定时间点或者CSN。
可以将表的状态恢复到指定时间点或者是表结构删除前的状态,恢复时间快。闪回技术能够有选择性的高效撤销一个已提交事务的影响,从人为错误中恢复。在采用闪回技术之前,只能通过备份恢复、PITR等手段找回已提交的数据库修改,恢复时长需要数分钟甚至数小时。采用闪回技术后,恢复已提交的数据库修改前的数据,只需要秒级,而且恢复时间和数据库大小无关。
闪回支持两种恢复模式:
- 基于MVCC多版本的数据恢复:适用于误删除、误更新、误插入数据的查询和恢复,用户通过配置旧版本保留时间,并执行相应的查询或恢复命令,查询或恢复到指定的时间点或CSN点。
- 基于类似windows系统回收站的恢复:适用于误DROP、误TRUNCATE的表的恢复。用户通过配置回收站开关,并执行相应的恢复命令,可以将误DROP、误TRUNCATE的表找回。
+ +当需要进行备份恢复操作时,主要从以下四个方面考虑数据备份方案。 + +- 备份对业务的影响在可接受范围。 + +- 数据库恢复效率。 + + 为尽量减小数据库故障的影响,要使恢复时间减到最少,从而使恢复的效率达到最高。 + +- 数据可恢复程度。 + + 当数据库失效后,要尽量减少数据损失。 + +- 数据库恢复成本。 + + 在现网选择备份策略时参考的因素比较多,如备份对象、数据大小、网络配置等,表2列出了可用的备份策略和每个备份策略的适用场景。 + + **表 2** 备份策略典型场景 + + | **备份策略** | **关键性能因素** | **典型数据量** | **性能规** | + | :------------: | :-------------------------: | :----------------------------: | :--------------------------------- | + | 数据库实例备份 | - 数据大小
- 网络配置 | 数据: PB级
对象: 约100万个 | 备份: 每个主机80 Mbit/s(NBU/EISOO+磁盘)约90%磁盘I/O速率(SSD/HDD) | + | 表备份 | - 表所在模式
- 网络配置(NBU) | 数据: 10 TB级 | 备份: 基于查询性能速度+I/O速度
说明:
多表备份时,备份耗时计算方式:
`总时间 = 表数量 x 起步时间 + 数据总量 / 数据备份速度`
其中:
- 磁盘起步间为5s左右,NBU起步时间比DISK长(取决于NBU部署方案)。
- 数据备份速度为单节点50MB/s左右(基于1GB大小的表,物理机备份到本地磁盘得出此速率)。
表越小,备份性能更低。 | diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-2-br.md b/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-2-br.md new file mode 100644 index 00000000..361c3e09 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-2-br.md @@ -0,0 +1,139 @@ +--- +title: 物理备份恢复 +summary: 物理备份恢复 +author: Liu Xu +date: 2021-03-04 +--- + +# 物理备份恢复 + +
+ +## gs_basebackup + +具体介绍,请参见[gs_basebackup](../../reference-guide/tool-reference/tools-used-in-the-internal-system/3-gs_basebackup.md)。 + +## PITR恢复 + +### 背景信息 + +当数据库崩溃或希望回退到数据库之前的某一状态时,MogDB的即时恢复功能(Point-In-Time Recovery,简称PITR)可以支持恢复到备份归档数据之后的任意时间点。 + + **说明:** + +- PITR仅支持恢复到物理备份数据之后的某一时间点。 +- 仅主节点可以进行PITR恢复,备机需要进行全量build达成与主机数据同步。 + +
+ +### 前提条件 + +- 基于经过物理备份的全量数据文件。 +- 基于已归档的WAL日志文件。 + +
+ +### PITR恢复流程 + +1. 将物理备份的文件替换目标数据库目录。 +2. 删除数据库目录下pg_xlog/中的所有文件。 +3. 将归档的WAL日志文件复制到pg_xlog文件中(此步骤可以省略,通过配置recovery.conf恢复命令文件中的restore_command项替代)。 +4. 在数据库目录下创建恢复命令文件recovery.conf,指定数据库恢复的程度。 +5. 启动数据库。 +6. 连接数据库,查看是否恢复到希望预期的状态。 +7. 若已经恢复到预期状态,通过pg_xlog_replay_resume()指令使主节点对外提供服务。 + +
+ +### recovery.conf文件配置 + +**归档恢复配置** + +- restore_command = string + + 这个SHELL命令是获取WAL文件系列中已归档的WAL文件。字符串中的任何一个%f是用归档检索中的文件名替换,并且%p是用服务器上的复制目的地的路径名替换。任意一个%r是用包含最新可用重启点的文件名替换。 + + 示例: + + ```bash + restore_command = 'cp /mnt/server/archivedir/%f %p' + ``` + +- archive_cleanup_command = string + + 这个选项参数声明一个shell命令。在每次重启时会执行这个shell命令。archive_cleanup_command为清理备库不需要的归档WAL文件提供一个机制。任何一个%r由包含最新可用重启点的文件名代替。这是最早的文件,因此必须保留以允许恢复能够重新启动,因此所有早于%r的文件可以安全的移除。 + + 示例: + + ```bash + archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r' + ``` + + 需要注意的是,如果多个备服务器从相同的归档路径恢复时,需要确保在任何一个备服务器在需要之前,不能删除WAL文件。 + +- recovery_end_command = string + + 这个参数是可选的,用于声明一个只在恢复完成时执行的SHELL命令。recovery_end_command是为以后的复制或恢复提供一个清理机制。 + +**恢复目标设置** + +- recovery_target_name = string + + 此参数声明命名还原到一个使用pg_create_restore_point()创建的还原点。 + + 示例: + + ```bash + recovery_target_name = 'restore_point_1' + ``` + +- recovery_target_time = timestamp + + 此参数声明命名还原到一个指定时间戳。 + + 示例: + + ```bash + recovery_target_time = '2020-01-01 12:00:00' + ``` + +- recovery_target_xid = string + + 这个参数声明还原到一个事务ID。 + + 示例: + + ```bash + recovery_target_xid = '3000' + ``` + +- recovery_target_lsn = string + + 这个参数声明还原到日志的指定LSN点。 + + 示例: + + ```bash + recovery_target_lsn = '0/0FFFFFF' + ``` + +- recovery_target_inclusive = boolean + + 声明是否在指定恢复目标(true)之后停止,或在(false)之前停止。改声明仅支持恢复目标为recovery_target_time,recovery_target_xid和recovery_target_lsn的配置。 + + 示例: + + ```bash + recovery_target_inclusive = true + ``` + +说明: + +- recovery_target_name,recovery_target_time,recovery_target_xid,recovery_target_lsn这四个配置项仅同时支持一项。 +- 如果不配置任何恢复目标,或配置目标不存在,则默认恢复到最新的WAL日志点。 + +
+ +## gs_probackup + +具体介绍,请参见[gs_probackup](../../reference-guide/tool-reference/tools-used-in-the-internal-system/15-gs_probackup.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-3-br.md b/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-3-br.md new file mode 100644 index 00000000..61249b98 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-3-br.md @@ -0,0 +1,24 @@ +--- +title: 逻辑备份恢复 +summary: 逻辑备份恢复 +author: Liu Xu +date: 2021-03-04 +--- + +# 逻辑备份恢复 + +## gs_dump + +具体介绍,请参见[gs_dump](../../reference-guide/tool-reference/server-tools/5-gs_dump.md)。 + +## gs_dumpall + +具体介绍,请参见[gs_dumpall](../../reference-guide/tool-reference/server-tools/6-gs_dumpall.md)。 + +## gs_restore + +具体介绍,请参见[gs_restore](../../reference-guide/tool-reference/server-tools/9-gs_restore.md)。 + +## gs_backup + +具体介绍,请参见[gs_backup](../../reference-guide/tool-reference/tools-used-in-the-internal-system/2-gs_backup.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-4-br.md b/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-4-br.md new file mode 100644 index 00000000..aa93fa5f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/br/1-4-br.md @@ -0,0 +1,204 @@ +--- +title: 闪回恢复 +summary: 闪回恢复 +author: Guo Huan +date: 2021-10-12 +--- + +# 闪回恢复 + +闪回恢复功能是数据库恢复技术的一环,可以有选择性的撤销一个已提交事务的影响,将数据从人为不正确的操作中进行恢复。在采用闪回技术之前,只能通过备份恢复、PITR等手段找回已提交的数据库修改,恢复时长需要数分钟甚至数小时。采用闪回技术后,恢复已提交的数据库修改前的数据,只需要秒级,而且恢复时间和数据库大小无关。 + +> **说明**: +> ASTORE引擎暂不支持闪回DROP/TRUNCATE。 + +**闪回支持两种恢复模式:** + +- 基于MVCC多版本的数据恢复(仅支持Ustore):适用于误删除、误更新、误插入数据的查询和恢复,用户通过配置旧版本保留时间,并执行相应的查询或恢复命令,查询或恢复到指定的时间点或CSN点。 +- 基于数据库回收站的恢复(仅支持Ustore):适用于误DROP、误TRUNCATE的表的恢复。用户通过配置回收站开关,并执行相应的恢复命令,可以将误DROP、误TRUNCATE的表找回。 + +**相关参数:** + +- [enable_default_ustore_table](../../reference-guide/guc-parameters/24-miscellaneous-parameters.md#enable_default_ustore_table)=on + + 开启默认支持Ustore存储引擎 + +- [undo_retention_time](../../reference-guide/guc-parameters/37-flashback.md#undo_retention_time) + + 设置undo旧版本保留时间。等同于允许闪回查询的时间跨度,超过该时间闪回查询可能会报`restore point not found`错误。 + +- [enable_recyclebin](../../reference-guide/guc-parameters/37-flashback.md#enable_recyclebin)=on + + 打开回收站 + +- [recyclebin_retention_time](../../reference-guide/guc-parameters/37-flashback.md#recyclebin_retention_time)=15min + + 设置回收站对象保留时间,超过该时间的回收站对象将被自动清理 + +
+ +## 闪回查询 + +### 背景信息 + +闪回查询可以查询过去某个时间点表的某个snapshot数据,这一特性可用于查看和逻辑重建意外删除或更改的受损数据。闪回查询基于MVCC多版本机制,通过检索查询旧版本,获取指定老版本数据。 + +### 前提条件 + +- undo_retention_time参数用于设置undo旧版本的保留时间。 + +### 语法 + +```ebnf+diagram +FlashBack ::= ( select_statement) TIMECAPSULE { TIMESTAMP | CSN } expression +``` + +语法树中“TIMECAPSULE {TIMESTAMP | CSN} expression”为闪回功能新增表达方式,其中TIMECAPSULE表示使用闪回功能,TIMESTAMP以及CSN表示闪回功能使用具体时间点信息或使用CSN(commit sequence number)信息。 + +### 参数说明 + +- TIMESTAMP + - 指要查询某个表在TIMESTAMP这个时间点上的数据,TIMESTAMP指一个具体的历史时间。 +- CSN + - 指要查询整个数据库逻辑提交序下某个CSN点的数据,CSN指一个具体逻辑提交时间点,数据库中的CSN为写一致性点,每个CSN代表整个数据库的一个一致性点,查询某个CSN下的数据代表SQL查询数据库在该一致性点的相关数据。 + +### 使用示例 + +- 示例1: + + ```sql + SELECT * FROM t1 TIMECAPSULE TIMESTAMP to_timestamp ('2020-02-11 10:13:22.724718', 'YYYY-MM-DD HH24:MI:SS.FF'); + ``` + +- 示例2: + + ```sql + SELECT * FROM t1 TIMECAPSULE CSN 9617; + ``` + +- 示例3: + + ```sql + SELECT * FROM t1 AS t TIMECAPSULE TIMESTAMP to_timestamp ('2020-02-11 10:13:22.724718', 'YYYY-MM-DD HH24:MI:SS.FF'); + ``` + +- 示例4: + + ```sql + SELECT * FROM t1 AS t TIMECAPSULE CSN 9617; + ``` + +## 闪回表 + +### 背景信息 + +闪回表可以将表恢复至特定时间点,当逻辑损坏仅限于一个或一组表,而不是整个数据库时,此特性可以快速恢复表的数据。闪回表基于MVCC多版本机制,通过删除指定时间点和该时间点之后的增量数据,并找回指定时间点和当前时间点删除的数据,实现表级数据还原。 + +### 前提条件 + +- undo_retention_time参数用于设置undo旧版本的保留时间。 + +### 语法 + +```ebnf+diagram +FlashBack ::= TIMECAPSULE TABLE table_name TO { TIMESTAMP | CSN } expression +``` + +### 使用示例 + +```sql +TIMECAPSULE TABLE t1 TO TIMESTAMP to_timestamp ('2020-02-11 10:13:22.724718', 'YYYY-MM-DD HH24:MI:SS.FF'); +TIMECAPSULE TABLE t1 TO CSN 9617; +``` + +## 闪回DROP/TRUNCATE + +### 背景信息 + +- 闪回DROP:可以恢复意外删除的表,从回收站(recycle bin)中恢复被删除的表及其附属结构如索引、表约束等。闪回drop是基于回收站机制,通过还原回收站中记录的表的物理文件,实现已drop表的恢复。 + +- 闪回TRUNCATE:可以恢复误操作或意外被进行truncate的表,从回收站中恢复被truncate的表及索引的物理数据。闪回truncate基于回收站机制,通过还原回收站中记录的表的物理文件,实现已truncate表的恢复。 + +### 前提条件 + +- 开启enable_recyclebin参数,启用回收站。 +- recyclebin_retention_time参数用于设置回收站对象保留时间,超过该时间的回收站对象将被自动清理。 + +### 相关语法 + +- 删除表 + + ```ebnf+diagram + DropTable ::= DROP TABLE table_name [PURGE] + ``` + +- 清理回收站对象 + + ```ebnf+diagram + PurgeRecyclebin ::= PURGE { TABLE { table_name } + | INDEX { index_name } + | RECYCLEBIN + } + ``` + +- 闪回被删除的表 + + ```ebnf+diagram + TimecapsuleTable ::= TIMECAPSULE TABLE { table_name } TO BEFORE DROP [RENAME TO new_tablename] + ``` + +- 截断表 + + ```ebnf+diagram + TruncateTable ::= TRUNCATE TABLE { table_name } [ PURGE ] + ``` + +- 闪回截断的表 + + ```ebnf+diagram + TimecapsuleTable ::= TIMECAPSULE TABLE { table_name } TO BEFORE TRUNCATE + ``` + +### 参数说明 + +- DROP/TRUNCATE TABLE table_name PURGE + - 默认将表数据放入回收站中,PURGE直接清理。 +- PURGE RECYCLEBIN + - 表示清理回收站对象。 +- **TO BEFORE DROP** + +使用这个子句检索回收站中已删除的表及其子对象。 + +可以指定原始用户指定的表的名称,或对象删除时数据库分配的系统生成名称。 + +- 回收站中系统生成的对象名称是唯一的。因此,如果指定系统生成名称,那么数据库检索指定的对象。使用“select * from pg_recyclebin;”语句查看回收站中的内容。 +- 如果指定了用户指定的名称,且如果回收站中包含多个该名称的对象,然后数据库检索回收站中最近移动的对象。如果想要检索更早版本的表,你可以这样做: + - 指定你想要检索的表的系统生成名称。 + - 执行TIMECAPSULE TABLE … TO BEFORE DROP语句,直到你要检索的表。 + - 恢复DROP表时,只恢复基表名,其他子对象名均保持回收站对象名。用户可根据需要,执行DDL命令手工调整子对象名。 + - 回收站对象不支持DML、DCL、DDL等写操作,不支持DQL查询操作(后续支持)。 + - 闪回点和当前点之间,执行过修改表结构或影响物理结构的语句,闪回失败。涉及namespace、表名改变等操作的DDL执行闪回报错: ERROR: recycle object %s desired does not exis;增加/删除/切割/合成等分区改变等操作的DDL执行闪回报错: ERROR: relation %s does not exis;其他情况报错:“ERROR:The table definition of %s has been changed. ”。 +- **RENAME TO** + +为从回收站中检索的表指定一个新名称。 + +- **TO BEFORE TRUNCATE** + +闪回到TRUNCATE之前。 + +### 语法示例 + +```sql +DROP TABLE t1 PURGE; + +PURGE TABLE t1; +PURGE TABLE "BIN$04LhcpndanfgMAAAAAANPw==$0"; +PURGE INDEX i1; +PURGE INDEX "BIN$04LhcpndanfgMAAAAAANPw==$0"; +PURGE RECYCLEBIN; + +TIMECAPSULE TABLE t1 TO BEFORE DROP; +TIMECAPSULE TABLE t1 TO BEFORE DROP RENAME TO new_t1; +TIMECAPSULE TABLE "BIN$04LhcpndanfgMAAAAAANPw==$0" TO BEFORE DROP; +TIMECAPSULE TABLE "BIN$04LhcpndanfgMAAAAAANPw==$0" TO BEFORE DROP RENAME TO new_t1; +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/column-store-tables-management.md b/product/zh/docs-mogdb/v3.1/administrator-guide/column-store-tables-management.md new file mode 100644 index 00000000..c1fc8d2b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/column-store-tables-management.md @@ -0,0 +1,401 @@ +--- +title: 列存表管理 +summary: 列存表管理 +author: Guo Huan +date: 2021-04-06 +--- + +# 列存表管理 + +
+ +## 什么是列存储 + +行存储是指将表按行存储到硬盘分区上,列存储是指将表按列存储到硬盘分区上。默认情况下,创建的表为行存储。行存储和列存储的差异请参见图1。 + +**图 1** 行存储和列存储的差异 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/column-store-tables-management.png) + +上图中,左上为行存表,右上为行存表在硬盘上的存储方式。左下为列存表,右下为列存表在硬盘上的存储方式。从上图可以很清楚地看到,行式存储下一张表的数据都是放在一起的,但列式存储下都被分开保存了。 + +
+ +## 行存表和列存表的优缺点及适用场景 + +行、列存储有如下优缺点: + +| **存储模型** | **优点** | **缺点** | +| :----------- | :--------------------| :-----------------------| +| 行存 | 数据被保存在一起。INSERT/UPDATE容易。 | 选择(Selection)时即使只涉及某几列,所有数据也都会被读取。 | +| 列存 | 查询时只有涉及到的列会被读取。投影(Projection)很高效。任何列都能作为索引。 | 选择完成时,被选择的列要重新组装。INSERT/UPDATE比较麻烦。 | + +一般情况下,如果表的字段比较多(大宽表),查询中涉及到的列不多的情况下,适合列存储。如果表的字段个数比较少,查询大部分字段,那么选择行存储比较好。 + +| 存储类型 | 适用场景 | +| :------- | :----------------- | +| 行存 | 点查询(返回记录少,基于索引的简单查询)。增、删、改操作较多的场景。 | +| 列存 | 统计分析类查询 (关联、分组操作较多的场景)。即席查询(查询条件不确定,行存表扫描难以使用索引)。 | + +MogDB支持行列混合存储。行、列存储模型各有优劣,建议根据实际情况选择。通常MogDB用于TP场景的数据库,默认使用行存储,仅对执行复杂查询且数据量大的AP场景时,才使用列存储。 + +
+ +## 行存表和列存表的选择 + +- 更新频繁程度 + + 数据如果频繁更新,选择行存表。 + +- 插入频繁程度 + + 频繁的少量插入,选择行存表。 + +- 表的列数 + + 表的列数很多,选择列存表。 + +- 查询的列数 + + 如果每次查询时,只涉及了表的少数(<50%总列数)几个列,选择列存表。 + +- 压缩率 + + 列存表比行存表压缩率高。但高压缩率会消耗更多的CPU资源。 + +
+ +## 列存表的限制 + +- 列存表不支持数组。 +- 列存表的数量建议不超过1000个。 +- 列存表的表级约束只支持PARTIAL CLUSTER KEY,不支持主外键等表级约束。 +- 列存表的字段约束只支持NULL、NOT NULL和DEFAULT常量值。 +- 列存表不支持alter命令修改字段约束。 +- 列存表支持delta表,受参数enable_delta_store 控制是否开启,受参数deltarow_threshold控制进入delta表的阀值。 + +
+ +## 列存相关参数 + +- cstore_buffers + + 列存所使用的共享缓冲区的大小,默认值: 32768KB。 + +- partition_mem_batch + + 指定缓存个数,为了优化对列存分区表的批量插入,在批量插入过程中会对数据进行缓存后再批量写盘。默认值: 256 。 + +- partition_max_cache_size + + 指定数据缓存区大小,为了优化对列存分区表的批量插入,在批量插入过程中会对数据进行缓存后再批量写盘。默认值: 2GB。 + +- enable_delta_store + + 为了增强列存单条数据导入的性能和解决磁盘冗余问题,是否需要开启列存delta表功能,与参数DELTAROW_THRESHOLD 配合使用。默认值: off。 + +
+ +## 建表语法 + +MogDB创建普通表默认是未压缩的行存表。 + +```bash +MogDB=# \dt +No relations found. +MogDB=# create table test_t(id serial primary key ,col1 varchar(8),col2 decimal(6,2),create_time timestamptz not null default now()); +NOTICE: CREATE TABLE will create implicit sequence "test_t_id_seq" for serial column "test_t.id" +NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index "test_t_pkey" for table "test_t" +CREATE TABLE +MogDB=# \dt+ + List of relations + Schema | Name | Type | Owner | Size | Storage | Description +--------+--------+-------+-------+---------+----------------------------------+------------- + public | test_t | table | omm | 0 bytes | {orientation=row,compression=no} | +(1 row) + +MogDB=# +``` + +创建列存表,需要指定**orientation=column**,默认压缩级别是low。 + +```sql +MogDB=# create table column_t(id serial,col1 varchar(8),col2 decimal(6,2),create_time timestamptz not null default now()) with (orientation=column ); +NOTICE: CREATE TABLE will create implicit sequence "column_t_id_seq" for serial column "column_t.id" +CREATE TABLE +MogDB=# \dt+ + List of relations + Schema | Name | Type | Owner | Size | Storage | Description +--------+----------+-------+-------+---------+--------------------------------------+------------- + public | column_t | table | omm | 16 kB | {orientation=column,compression=low} | + public | test_t | table | omm | 0 bytes | {orientation=row,compression=no} | +(2 rows) + +MogDB=# +MogDB=# \d+ column_t + Table "public.column_t" + Column | Type | Modifiers | Storage | Stats target | Description +-------------+--------------------------+-------------------------------------------------------+----------+--------------+------------- + id | integer | not null default nextval('column_t_id_seq'::regclass) | plain | | + col1 | character varying(8) | | extended | | + col2 | numeric(6,2) | | main | | + create_time | timestamp with time zone | not null default now() | plain | | +Has OIDs: no +Options: orientation=column, compression=low +``` + +列存表添加局部聚簇存储列。 + +```sql +MogDB=# \d+ column_t + Table "public.column_t" + Column | Type | Modifiers | Storage | Stats target | Description +-------------+--------------------------+-------------------------------------------------------+----------+--------------+------------- + id | integer | not null default nextval('column_t_id_seq'::regclass) | plain | | + col1 | character varying(8) | | extended | | + col2 | numeric(6,2) | | main | | + create_time | timestamp with time zone | not null default now() | plain | | +Has OIDs: no +Options: orientation=column, compression=low + +MogDB=# alter table column_t add PARTIAL CLUSTER KEY(id); +ALTER TABLE +MogDB=# \d+ column_t + Table "public.column_t" + Column | Type | Modifiers | Storage | Stats target | Description +-------------+--------------------------+-------------------------------------------------------+----------+--------------+------------- + id | integer | not null default nextval('column_t_id_seq'::regclass) | plain | | + col1 | character varying(8) | | extended | | + col2 | numeric(6,2) | | main | | + create_time | timestamp with time zone | not null default now() | plain | | +Partial Cluster : + "column_t_cluster" PARTIAL CLUSTER KEY (id) +Has OIDs: no +Options: orientation=column, compression=low + +MogDB=# +``` + +直接创建带局部聚簇存储的列存表。 + +```sql +MogDB=# create table column_c(id serial,col1 varchar(8),col2 decimal(6,2),create_time timestamptz not null default now(),PARTIAL CLUSTER KEY(id)) with (orientation=column ); +NOTICE: CREATE TABLE will create implicit sequence "column_c_id_seq" for serial column "column_c.id" +CREATE TABLE +MogDB=# \d+ column_c + Table "public.column_c" + Column | Type | Modifiers | Storage | Stats target | Description +-------------+--------------------------+-------------------------------------------------------+----------+--------------+------------- + id | integer | not null default nextval('column_c_id_seq'::regclass) | plain | | + col1 | character varying(8) | | extended | | + col2 | numeric(6,2) | | main | | + create_time | timestamp with time zone | not null default now() | plain | | +Partial Cluster : + "column_c_cluster" PARTIAL CLUSTER KEY (id) +Has OIDs: no +Options: orientation=column, compression=low + +MogDB=# +``` + +有关列存表支持的数据类型,请参见参考指南>支持的数据类型下的[列存表支持的数据类型](../reference-guide/supported-data-types/16-data-types-supported-by-column-store-tables.md). + +
+ +## 列存与行存对比 + +**磁盘使用空间** + +- 列存表默认大小16K,low压缩级别。 + +- 行存表默认大小0bytes,非压缩级别。 + +- 分别向两个表中插入100万条数据,占用磁盘大小对比。 + + ```sql + MogDB=# \dt+ + List of relations + Schema | Name | Type | Owner | Size | Storage | Description + --------+-----------+-------+-------+---------+-----------------------------------------+------------- + public | column_t | table | omm | 16 kB | {orientation=column,compression=low} | + public | column_th | table | omm | 16 kB | {orientation=column,compression=high} | + public | column_tm | table | omm | 16 kB | {orientation=column,compression=middle} | + public | row_tc | table | omm | 0 bytes | {orientation=row,compression=yes} | + public | test_t | table | omm | 0 bytes | {orientation=row,compression=no} | + (5 rows) + MogDB=# insert into column_t select generate_series(1,1000000),left(md5(random()::text),8),random()::numeric(6,2); + INSERT 0 1000000 + Time: 11328.880 ms + MogDB=# insert into column_th select generate_series(1,1000000),left(md5(random()::text),8),random()::numeric(6,2); + INSERT 0 1000000 + Time: 10188.634 ms + MogDB=# insert into column_tm select generate_series(1,1000000),left(md5(random()::text),8),random()::numeric(6,2); + INSERT 0 1000000 + Time: 9802.739 ms + MogDB=# insert into test_t select generate_series(1,1000000),left(md5(random()::text),8),random()::numeric(6,2); + INSERT 0 1000000 + Time: 17404.945 ms + MogDB=# insert into row_tc select generate_series(1,1000000),left(md5(random()::text),8),random()::numeric(6,2); + INSERT 0 1000000 + Time: 12394.866 ms + MogDB=# \dt+ + List of relations + Schema | Name | Type | Owner | Size | Storage | Description + --------+-----------+-------+-------+----------+-----------------------------------------+------------- + public | column_t | table | omm | 12 MB | {orientation=column,compression=low} | + public | column_th | table | omm | 8304 kB | {orientation=column,compression=high} | + public | column_tm | table | omm | 10168 kB | {orientation=column,compression=middle} | + public | row_tc | table | omm | 58 MB | {orientation=row,compression=yes} | + public | test_t | table | omm | 58 MB | {orientation=row,compression=no} | + (5 rows) + MogDB=# + ``` + +- 列存表开启的压缩级别越高,占用磁盘空间越少。 + +- 行存表开启压缩后,磁盘空间大小占比减少不明显。 + +- 列存表占用磁盘空间比行存表占用磁盘空间少近6倍。 + +**DML对比** + +查找单列: + +```sql +--- +---按范围查找,列存比行存快近20倍 +--- +MogDB=# select col1 from test_t where id>=100010 and id<100020; + col1 +---------- + 4257a3f3 + 3d397284 + 64343438 + 6eb7bdb7 + d1c9073d + 6aeb037c + 1d424974 + 223235ab + 329de235 + 2f02adc1 +(10 rows) + +Time: 77.341 ms +MogDB=# select col1 from column_t where id>=100010 and id<100020; + col1 +---------- + d4837c30 + 87a46f7a + 2f42a9c9 + 4481c793 + 68800204 + 613b9205 + 9d8f4a0a + 5cc4ff9e + f948cd10 + f2775cee +(10 rows) + +Time: 3.884 ms + +--- +---随机查找,列存比行存快近35倍 +--- + +MogDB=# select col1 from test_t limit 10; + col1 +---------- + c2780d93 + 294be14d + 4e53b761 + 2c10f8a2 + ae776743 + 7d683c66 + b3b40054 + 7e56edf9 + a7b7336e + ea3d47d9 +(10 rows) + +Time: 249.887 ms +MogDB=# select col1 from column_t limit 10; + col1 +---------- + a745d77b + 4b6df494 + 76fed9c1 + 70c9664d + 3384de8a + 4158f3bf + 5d1c3b9f + 341876bb + f396f4ed + abfd78bb +(10 rows) + +Time: 7.738 ms +``` + +查找全部数据: + +```sql +--- +---行存比列存查询快30% +--- +MogDB=# select * from test_t limit 10; + id | col1 | col2 | create_time +----+----------+------+------------------------------- + 1 | c2780d93 | .37 | 2020-10-26 14:27:33.304108+08 + 2 | 294be14d | .57 | 2020-10-26 14:27:33.304108+08 + 3 | 4e53b761 | .98 | 2020-10-26 14:27:33.304108+08 + 4 | 2c10f8a2 | .27 | 2020-10-26 14:27:33.304108+08 + 5 | ae776743 | .97 | 2020-10-26 14:27:33.304108+08 + 6 | 7d683c66 | .58 | 2020-10-26 14:27:33.304108+08 + 7 | b3b40054 | .44 | 2020-10-26 14:27:33.304108+08 + 8 | 7e56edf9 | .43 | 2020-10-26 14:27:33.304108+08 + 9 | a7b7336e | .31 | 2020-10-26 14:27:33.304108+08 + 10 | ea3d47d9 | .42 | 2020-10-26 14:27:33.304108+08 +(10 rows) + +Time: 6.822 ms + +MogDB=# select * from column_t limit 10; + id | col1 | col2 | create_time +----+----------+------+------------------------------- + 1 | a745d77b | .33 | 2020-10-26 14:28:20.633253+08 + 2 | 4b6df494 | .42 | 2020-10-26 14:28:20.633253+08 + 3 | 76fed9c1 | .73 | 2020-10-26 14:28:20.633253+08 + 4 | 70c9664d | .74 | 2020-10-26 14:28:20.633253+08 + 5 | 3384de8a | .48 | 2020-10-26 14:28:20.633253+08 + 6 | 4158f3bf | .59 | 2020-10-26 14:28:20.633253+08 + 7 | 5d1c3b9f | .63 | 2020-10-26 14:28:20.633253+08 + 8 | 341876bb | .97 | 2020-10-26 14:28:20.633253+08 + 9 | f396f4ed | .73 | 2020-10-26 14:28:20.633253+08 + 10 | abfd78bb | .30 | 2020-10-26 14:28:20.633253+08 +(10 rows) + +Time: 9.982 ms +``` + +更新数据: + +```sql +--- +---直接更新一个字段,列存比行存快近7倍 +--- +MogDB=# update test_t set col1=col1; +UPDATE 1000000 +Time: 19779.978 ms +MogDB=# update column_t set col1=col1; +UPDATE 1000000 +Time: 2702.339 ms +``` + +
+ +## 总结 + +1. 列存表比行存表在磁盘空间占用上节省近6倍。 +2. 查询指定字段,列存表比行存表快约20-35倍。 +3. select * 的方式,列存表比行存表慢30%。 +4. 默认压缩方式批量导入数据,列存表比行存表快40%。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/1-using-gs_dump-and-gs_dumpall-to-export-data-overview.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/1-using-gs_dump-and-gs_dumpall-to-export-data-overview.md new file mode 100644 index 00000000..ee989263 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/1-using-gs_dump-and-gs_dumpall-to-export-data-overview.md @@ -0,0 +1,91 @@ +--- +title: 使用gs_dump和gs_dumpall命令导出数据概述 +summary: 使用gs_dump和gs_dumpall命令导出数据概述 +author: Guo Huan +date: 2021-03-04 +--- + +# 使用gs_dump和gs_dumpall命令导出数据概述 + +MogDB提供的gs_dump和gs_dumpall工具,能够帮助用户导出需要的数据库对象或其相关信息。通过导入工具将导出的数据信息导入至需要的数据库,可以完成数据库信息的迁移。gs_dump支持导出单个数据库或其内的对象,而gs_dumpall支持导出MogDB中所有数据库或各库的公共全局对象。详细的使用场景见[表1](#适用场景)。 + +**表 1** 适用场景 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
适用场景支持的导出粒度支持的导出格式配套的导入方法
导出单个数据库数据库级导出。
+ - 导出全量信息。
使用导出的全量信息可以创建一个与当前库相同的数据库,且库中数据也与当前库相同。
+ - 仅导出库中所有对象的定义,包含库定义、函数定义、模式定义、表定义、索引定义和存储过程定义等。
+ 使用导出的对象定义,可以快速创建一个相同的数据库,但是库中并无原数据库的数据。
+ - 仅导出数据。
+ - 纯文本格式
+ - 自定义归档格式
+ - 目录归档格式
+ - tar归档格式 +
+ - 纯文本格式数据文件导入请参见使用gsql元命令导入数据。
+ - 自定义归档格式、目录归档格式和tar归档格式数据文件导入请参见使用gs_restore命令导入数据。
模式级导出。
+ - 导出模式的全量信息。
+ - 仅导出模式中数据。
+ - 仅导出对象的定义,包含表定义、存储过程定义和索引定义等。 +
表级导出。
+ - 导出表的全量信息。
+ - 仅导出表中数据。
+ - 仅导出表的定义。 +
导出所有数据库数据库级导出。
+ - 导出全量信息。
使用导出的全量信息可以创建与当前主机相同的一个主机环境,拥有相同数据库和公共全局对象,且库中数据也与当前各库相同。
+ - 仅导出各数据库中的对象定义,包含表空间、库定义、函数定义、模式定义、表定义、索引定义和存储过程定义等。
+ 使用导出的对象定义,可以快速创建与当前主机相同的一个主机环境,拥有相同的数据库和表空间,但是库中并无原数据库的数据。
+ - 仅导出数据。
纯文本格式数据文件导入请参见使用gsql元命令导入数据。
各库公共全局对象导出。
+- 仅导出表空间信息。
+- 仅导出角色信息。
+- 导出角色与表空间。
+ +gs_dump和gs_dumpall通过-U指定执行导出的用户帐户。如果当前使用的帐户不具备导出所要求的权限时,会无法导出数据。此时,可在导出命令中设置-role参数来指定具备权限的角色。在执行命令后,gs_dump和gs_dumpall会使用-role参数指定的角色,完成导出动作。可使用该功能的场景请参见[表1](#适用场景),详细操作请参见[无权限角色导出数据](4-data-export-by-a-user-without-required-permissions.md)。 + +gs_dump和gs_dumpall通过对导出的数据文件加密,导入时对加密的数据文件进行解密,可以防止数据信息泄露,为数据库的安全提供保证。注意,使用gs_dump加密的纯文本格式文件,如果导出的数据库中包含存储过程,不支持使用gsql命令恢复文件,请使用另外三种模式导出数据库,并使用gs_restore恢复。 + +gs_dump和gs_dumpall工具在进行数据导出时,其他用户可以访问数据库(读或写)。 + +gs_dump和gs_dumpall工具支持导出完整一致的数据。例如,T1时刻启动gs_dump导出A数据库,或者启动gs_dumpall导出MogDB数据库,那么导出数据结果将会是T1时刻A数据库或者该MogDB数据库的数据状态,T1时刻之后对A数据库或MogDB数据库的修改不会被导出。 + +**注意事项** + +- 禁止修改导出的文件和内容,否则可能无法恢复成功。 + +- 如果数据库中包含的对象数量(数据表、视图、索引)在50万以上,为了提高性能且避免出现内存问题,建议通过gs_guc工具设置数据库节点的如下参数(如果参数值大于如下建议值,则无需设置)。 + + ```bash + gs_guc set -N all -I all -c 'max_prepared_transactions = 1000' + gs_guc set -N all -I all -c 'max_locks_per_transaction = 512' + ``` + +- 为了保证数据一致性和完整性,导出工具会对需要转储的表设置共享锁。如果表在别的事务中设置了共享锁,gs_dump和gs_dumpall会等待锁释放后锁定表。如果无法在指定时间内锁定某个表,转储会失败。用户可以通过指定-lock-wait-timeout选项,自定义等待锁超时时间。 + +- 由于gs_dumpall读取所有数据库中的表,因此必须以MogDB管理员身份进行连接,才能导出完整文件。在使用gsql执行脚本文件导入时,同样需要管理员权限,以便添加用户和组,以及创建数据库。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/2-exporting-a-single-database.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/2-exporting-a-single-database.md new file mode 100644 index 00000000..5a47288e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/2-exporting-a-single-database.md @@ -0,0 +1,305 @@ +--- +title: 导出单个数据库 +summary: 导出单个数据库 +author: Guo Huan +date: 2021-03-04 +--- + +# 导出单个数据库 + +
+ +## 导出数据库 + +MogDB支持使用gs_dump工具导出某个数据库级的内容,包含数据库的数据和所有对象定义。可根据需要自定义导出如下信息: + +- 导出数据库全量信息,包含数据和所有对象定义。 + + 使用导出的全量信息可以创建一个与当前库相同的数据库,且库中数据也与当前库相同。 + +- 仅导出所有对象定义,包括: 库定义、函数定义、模式定义、表定义、索引定义和存储过程定义等。 + + 使用导出的对象定义,可以快速创建一个相同的数据库,但是库中并无原数据库的数据。 + +- 仅导出数据,不包含所有对象定义。 + +
+ +### 操作步骤 + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用gs_dump导出userdatabase数据库。 + + ```bash + gs_dump -U jack -f /home/omm/backup/userdatabase_backup.tar -p 8000 postgres -F t + ``` + + **表 1** 常用参数说明 + + | 参数 | 参数说明 | 举例 | + | :------- | :------------------------------------ | :----------------------| + | -U | 连接数据库的用户名。
- 说明:
不指定连接数据库的用户名时,默认以安装时创建的初始系统管理员连接。 | -U jack | + | -W | 指定用户连接的密码。
- 如果主机的认证策略是trust,则不会对数据库管理员进行密码验证,即无需输入-W选项;
- 如果没有-W选项,并且不是数据库管理员,会提示用户输入密码。 | -W abcd@123 | + | -f | 将导出文件发送至指定目录文件夹。如果这里省略,则使用标准输出。 | -f /home/omm/backup/**postgres**_backup.tar | + | -p | 指定服务器所监听的TCP端口或本地Unix域套接字后缀,以确保连接。 | -p 8000 | + | dbname | 需要导出的数据库名称 | postgres | + | -F | 选择导出文件格式。-F参数值如下:
- p: 纯文本格式
- c: 自定义归档
- d: 目录归档格式
- t: tar归档格式 | -F t | + + 其他参数说明请参见《参考指南》中“工具参考 > 服务端工具 > [gs_dump](../../../reference-guide/tool-reference/server-tools/5-gs_dump.md)”章节。 + +
+ +### 示例 + +示例一: 执行gs_dump,导出postgres数据库全量信息,导出文件格式为sql文本格式。 + +```bash +gs_dump -f /home/omm/backup/postgres_backup.sql -p 8000 postgres -F p +Password: +gs_dump[port='8000'][postgres][2017-07-21 15:36:13]: dump database postgres successfully +gs_dump[port='8000'][postgres][2017-07-21 15:36:13]: total time: 3793 ms +``` + +示例二: 执行gs_dump,仅导出postgres数据库中的数据,不包含数据库对象定义,导出文件格式为自定义归档格式。 + +```bash +gs_dump -f /home/omm/backup/postgres_data_backup.dmp -p 8000 postgres -a -F c +Password: +gs_dump[port='8000'][postgres][2017-07-21 15:36:13]: dump database postgres successfully +gs_dump[port='8000'][postgres][2017-07-21 15:36:13]: total time: 3793 ms +``` + +示例三: 执行gs_dump,仅导出postgres数据库所有对象的定义,导出文件格式为sql文本格式。 + +```bash +gs_dump -f /home/omm/backup/postgres_def_backup.sql -p 8000 postgres -s -F p +Password: +gs_dump[port='8000'][postgres][2017-07-20 15:04:14]: dump database postgres successfully +gs_dump[port='8000'][postgres][2017-07-20 15:04:14]: total time: 472 ms +``` + +示例四: 执行gs_dump,仅导出postgres数据库的所有对象的定义,导出文件格式为文本格式,并对导出文件进行加密。 + +```bash +gs_dump -f /home/omm/backup/postgres_def_backup.sql -p 8000 postgres --with-encryption AES128 --with-key 1234567812345678 -s -F p +Password: +gs_dump[port='8000'][postgres][2018-11-14 11:25:18]: dump database postgres successfully +gs_dump[port='8000'][postgres][2018-11-14 11:25:18]: total time: 1161 ms +``` + +
+ +## 导出模式 + +MogDB目前支持使用gs_dump工具导出模式级的内容,包含模式的数据和定义。用户可通过灵活的自定义方式导出模式内容,不仅支持选定一个模式或多个模式的导出,还支持排除一个模式或者多个模式的导出。可根据需要自定义导出如下信息: + +- 导出模式全量信息,包含数据和对象定义。 +- 仅导出数据,即模式包含表中的数据,不包含对象定义。 +- 仅导出模式对象定义,包括: 表定义、存储过程定义和索引定义等。 + +
+ +### 操作步骤 + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用gs_dump同时导出hr和public模式。 + + ```bash + gs_dump -W Bigdata@123 -U jack -f /home/omm/backup/MPPDB_schema_backup -p 8000 human_resource -n hr -n public -F d + ``` + + **表 1** 常用参数说明 + + | 参数 | 参数说明 | 举例 | + | :------- | :------------------------------ | :----------------------| + | -U | 连接数据库的用户名。 | -U jack | + | -W | 指定用户连接的密码。
- 如果主机的认证策略是trust,则不会对数据库管理员进行密码验证,即无需输入-W选项。
- 如果没有-W选项,并且不是数据库管理员,会提示用户输入密码。 | -W Bigdata@123 | + | -f | 将导出文件发送至指定目录文件夹。如果这里省略,则使用标准输出。 | -f /home/omm/backup/MPPDB*_*schema_backup | + | -p | 指定服务器所监听的TCP端口或本地Unix域套接字后缀,以确保连接。 | -p 8000 | + | dbname | 需要导出的数据库名称 | human_resource | + | -n | 只导出与模式名称匹配的模式,此选项包括模式本身和所有它包含的对象。
- 单个模式: -n **schemaname**
- 多个模式: 多次输入-n **schemaname** | - 单个模式: -n hr
- 多个模式: -n hr -n public | + | -F | 选择导出文件格式。-F参数值如下:
- p: 纯文本格式
- c: 自定义归档
- d: 目录归档格式
- t: tar归档格式 | -F d | + + 其他参数说明请参见《参考指南》中“工具参考 > 服务端工具 > [gs_dump](../../../reference-guide/tool-reference/server-tools/5-gs_dump.md)”章节。 + +
+ +### 示例 + +示例一: 执行gs_dump,导出hr模式全量信息,导出文件格式为文本格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_schema_backup.sql -p 8000 human_resource -n hr -F p +gs_dump[port='8000'][human_resource][2017-07-21 16:05:55]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 16:05:55]: total time: 2425 ms +``` + +示例二: 执行gs_dump,仅导出hr模式的数据,导出文件格式为tar归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_schema_data_backup.tar -p 8000 human_resource -n hr -a -F t +gs_dump[port='8000'][human_resource][2018-11-14 15:07:16]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2018-11-14 15:07:16]: total time: 1865 ms +``` + +示例三: 执行gs_dump,仅导出hr模式的定义,导出文件格式为目录归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_schema_def_backup -p 8000 human_resource -n hr -s -F d +gs_dump[port='8000'][human_resource][2018-11-14 15:11:34]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2018-11-14 15:11:34]: total time: 1652 ms +``` + +示例四: 执行gs_dump,导出human_resource数据库时,排除hr模式,导出文件格式为自定义归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_schema_backup.dmp -p 8000 human_resource -N hr -F c +gs_dump[port='8000'][human_resource][2017-07-21 16:06:31]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 16:06:31]: total time: 2522 ms +``` + +示例五: 执行gs_dump,同时导出hr和public模式,且仅导出模式定义,导出文件格式为tar归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_schema_backup1.tar -p 8000 human_resource -n hr -n public -s -F t +gs_dump[port='8000'][human_resource][2017-07-21 16:07:16]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 16:07:16]: total time: 2132 ms +``` + +示例六: 执行gs_dump,导出human_resource数据库时,排除hr和public模式,导出文件格式为自定义归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_schema_backup2.dmp -p 8000 human_resource -N hr -N public -F c +gs_dump[port='8000'][human_resource][2017-07-21 16:07:55]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 16:07:55]: total time: 2296 ms +``` + +示例七: 执行gs_dump,导出public模式下所有表(视图、序列和外表)和hr模式中staffs表,包含数据和表定义,导出文件格式为自定义归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_backup3.dmp -p 8000 human_resource -t public.* -t hr.staffs -F c +gs_dump[port='8000'][human_resource][2018-12-13 09:40:24]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2018-12-13 09:40:24]: total time: 896 ms +``` + +
+ +## 导出表 + +MogDB支持使用gs_dump工具导出表级的内容,包含表定义和表数据。视图、序列和外表属于特殊的表。用户可通过灵活的自定义方式导出表内容,不仅支持选定一个表或多个表的导出,还支持排除一个表或者多个表的导出。可根据需要自定义导出如下信息: + +- 导出表全量信息,包含表数据和表定义。 +- 仅导出数据,不包含表定义。 +- 仅导出表定义。 + +
+ +### 操作步骤 + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用gs_dump同时导出指定表hr.staffs和hr.employments。 + + ```bash + gs_dump -W Bigdata@123 -U jack -f /home/omm/backup/MPPDB_table_backup -p 8000 human_resource -t hr.staffs -t hr.employments -F d + ``` + + **表 1** 常用参数说明 + + | 参数 | 参数说明 | 举例 | + | :----- | :----------------------------------------------------------- | :----------------------------------------------------------- | + | -U | 连接数据库的用户名。 | -U jack | + | -W | 指定用户连接的密码。
- 如果主机的认证策略是trust,则不会对数据库管理员进行密码验证,即无需输入-W选项。
- 如果没有-W选项,并且不是数据库管理员,会提示用户输入密码。 | -W Bigdata@123 | + | -f | 将导出文件发送至指定目录文件夹。如果这里省略,则使用标准输出。 | -f /home/omm/backup/ MPPDB_table_backup | + | -p | 指定服务器所监听的TCP端口或本地Unix域套接字后缀,以确保连接。 | -p 8000 | + | dbname | 需要导出的数据库名称。 | human_resource | + | -t | 指定导出的表(或视图、序列、外表),可以使用多个-t选项来选择多个表,也可以使用通配符指定多个表对象。当使用通配符指定多个表对象时,注意给pattern打引号,防止shell扩展通配符。
- 单个表: -t **schema.table**
- 多个表: 多次输入-t **schema.table** | - 单个表: -t hr.staffs
- 多个表: -t hr.staffs -t hr.employments | + | -F | 选择导出文件格式。-F参数值如下:
- p: 纯文本格式
- c: 自定义归档
- d: 目录归档格式
- t: tar归档格式 | -F d | + + 其他参数说明请参见《参考指南》中“工具参考 > 服务端工具 > [gs_dump](../../../reference-guide/tool-reference/server-tools/5-gs_dump.md)”章节。 + +
+ +### 示例 + +示例一: 执行gs_dump,导出表hr.staffs的定义和数据,导出文件格式为文本格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_backup.sql -p 8000 human_resource -t hr.staffs -F p +gs_dump[port='8000'][human_resource][2017-07-21 17:05:10]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 17:05:10]: total time: 3116 ms +``` + +示例二: 执行gs_dump,只导出表hr.staffs的数据,导出文件格式为tar归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_data_backup.tar -p 8000 human_resource -t hr.staffs -a -F t +gs_dump[port='8000'][human_resource][2017-07-21 17:04:26]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 17:04:26]: total time: 2570 ms +``` + +示例三: 执行gs_dump,导出表hr.staffs的定义,导出文件格式为目录归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_def_backup -p 8000 human_resource -t hr.staffs -s -F d +gs_dump[port='8000'][human_resource][2017-07-21 17:03:09]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 17:03:09]: total time: 2297 ms +``` + +示例四: 执行gs_dump,不导出表hr.staffs,导出文件格式为自定义归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_backup4.dmp -p 8000 human_resource -T hr.staffs -F c +gs_dump[port='8000'][human_resource][2017-07-21 17:14:11]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 17:14:11]: total time: 2450 ms +``` + +示例五: 执行gs_dump,同时导出两个表hr.staffs和hr.employments,导出文件格式为文本格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_backup1.sql -p 8000 human_resource -t hr.staffs -t hr.employments -F p +gs_dump[port='8000'][human_resource][2017-07-21 17:19:42]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 17:19:42]: total time: 2414 ms +``` + +示例六: 执行gs_dump,导出时,排除两个表hr.staffs和hr.employments,导出文件格式为文本格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_backup2.sql -p 8000 human_resource -T hr.staffs -T hr.employments -F p +gs_dump[port='8000'][human_resource][2017-07-21 17:21:02]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 17:21:02]: total time: 3165 ms +``` + +示例七: 执行gs_dump,导出表hr.staffs的定义和数据,只导出表hr.employments的定义,导出文件格式为tar归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_backup3.tar -p 8000 human_resource -t hr.staffs -t hr.employments --exclude-table-data hr.employments -F t +gs_dump[port='8000'][human_resource][2018-11-14 11:32:02]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2018-11-14 11:32:02]: total time: 1645 ms +``` + +示例八: 执行gs_dump,导出表hr.staffs的定义和数据,并对导出文件进行加密,导出文件格式为文本格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_backup4.sql -p 8000 human_resource -t hr.staffs --with-encryption AES128 --with-key abcdefg_?1234567 -F p +gs_dump[port='8000'][human_resource][2018-11-14 11:35:30]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2018-11-14 11:35:30]: total time: 6708 ms +``` + +示例九: 执行gs_dump,导出public模式下所有表(包括视图、序列和外表)和hr模式中staffs表,包含数据和表定义,导出文件格式为自定义归档格式。 + +```bash +gs_dump -W Bigdata@123 -f /home/omm/backup/MPPDB_table_backup5.dmp -p 8000 human_resource -t public.* -t hr.staffs -F c +gs_dump[port='8000'][human_resource][2018-12-13 09:40:24]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2018-12-13 09:40:24]: total time: 896 ms +``` + +示例十: 执行gs_dump,仅导出依赖于t1模式下的test1表对象的视图信息,导出文件格式为目录归档格式。 + +```bash +gs_dump -W Bigdata@123 -U jack -f /home/omm/backup/MPPDB_view_backup6 -p 8000 human_resource -t t1.test1 --include-depend-objs --exclude-self -F d +gs_dump[port='8000'][jack][2018-11-14 17:21:18]: dump database human_resource successfully +gs_dump[port='8000'][jack][2018-11-14 17:21:23]: total time: 4239 ms +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/3-exporting-all-databases.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/3-exporting-all-databases.md new file mode 100644 index 00000000..7456a8ef --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/3-exporting-all-databases.md @@ -0,0 +1,133 @@ +--- +title: 导出所有数据库 +summary: 导出所有数据库 +author: Guo Huan +date: 2021-03-04 +--- + +# 导出所有数据库 + +
+ +## 导出所有数据库 + +MogDB支持使用gs_dumpall工具导出所有数据库的全量信息,包含MogDB中每个数据库信息和公共的全局对象信息。可根据需要自定义导出如下信息: + +- 导出所有数据库全量信息,包含MogDB中每个数据库信息和公共的全局对象信息(包含角色和表空间信息)。 + + 使用导出的全量信息可以创建与当前主机相同的一个主机环境,拥有相同数据库和公共全局对象,且库中数据也与当前各库相同。 + +- 仅导出数据,即导出每个数据库中的数据,且不包含所有对象定义和公共的全局对象信息。 + +- 仅导出所有对象定义,包括: 表空间、库定义、函数定义、模式定义、表定义、索引定义和存储过程定义等。 + + 使用导出的对象定义,可以快速创建与当前主机相同的一个主机环境,拥有相同的数据库和表空间,但是库中并无原数据库的数据。 + +
+ +### 操作步骤 + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用gs_dumpall一次导出所有数据库信息。 + + ```bash + gs_dumpall -W Bigdata@123 -U omm -f /home/omm/backup/MPPDB_backup.sql -p 8000 + ``` + + **表 1** 常用参数说明 + + | 参数 | 参数说明 | 举例 | + | :------- | :----------------------------------------------------------------- | :----------------------| + | -U | 连接数据库的用户名,需要是MogDB管理员用户。 | -U omm | + | -W | 指定用户连接的密码。
- 如果主机的认证策略是trust,则不会对数据库管理员进行密码验证,即无需输入-W选项;
- 如果没有-W选项,并且不是数据库管理员,会提示用户输入密码。 | -W Bigdata@123 | + | -f | 将导出文件发送至指定目录文件夹。如果这里省略,则使用标准输出。 | -f /home/omm/backup/MPPDB_backup.sql | + | -p | 指定服务器所监听的TCP端口或本地Unix域套接字后缀,以确保连接。 | -p 8000 | + + 其他参数说明请参见《参考指南》中“工具参考 > 服务端工具 > [gs_dumpall](../../../reference-guide/tool-reference/server-tools/6-gs_dumpall.md)”章节。 + +
+ +### 示例 + +示例一: 执行gs_dumpall,导出所有数据库全量信息(omm用户为管理员用户),导出文件为文本格式。执行命令后,会有很长的打印信息,最终出现total time即代表执行成功。示例中将不体现中间的打印信息。 + +```bash +gs_dumpall -W Bigdata@123 -U omm -f /home/omm/backup/MPPDB_backup.sql -p 8000 +gs_dumpall[port='8000'][2017-07-21 15:57:31]: dumpall operation successful +gs_dumpall[port='8000'][2017-07-21 15:57:31]: total time: 9627 ms +``` + +示例二: 执行gs_dumpall,仅导出所有数据库定义(omm用户为管理员用户),导出文件为文本格式。执行命令后,会有很长的打印信息,最终出现total time即代表执行成功。示例中将不体现中间的打印信息。 + +```bash +gs_dumpall -W Bigdata@123 -U omm -f /home/omm/backup/MPPDB_backup.sql -p 8000 -s +gs_dumpall[port='8000'][2018-11-14 11:28:14]: dumpall operation successful +gs_dumpall[port='8000'][2018-11-14 11:28:14]: total time: 4147 ms +``` + +示例三: 执行gs_dumpall,仅导出所有数据库中数据,并对导出文件进行加密,导出文件为文本格式。执行命令后,会有很长的打印信息,最终出现total time即代表执行成功。示例中将不体现中间的打印信息。 + +```bash +gs_dumpall -f /home/omm/backup/MPPDB_backup.sql -p 8000 -a --with-encryption AES128 --with-key 1234567812345678 +gs_dumpall[port='8000'][2018-11-14 11:32:26]: dumpall operation successful +gs_dumpall[port='8000'][2018-11-14 11:23:26]: total time: 4147 ms +``` + +
+ +## 导出全局对象 + +MogDB支持使用gs_dumpall工具导出所有数据库公共的全局对象,包含数据库用户和组,表空间及属性(例如: 适用于数据库整体的访问权限)信息。 + +
+ +### 操作步骤 + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用gs_dumpall导出表空间对象信息。 + + ```bash + gs_dumpall -W Bigdata@123 -U omm -f /home/omm/backup/MPPDB_tablespace.sql -p 8000 -t + ``` + + **表 1** 常用参数说明 + + | 参数 | 参数说明 | 举例 | + | :------- | :----------------------------------------------------------------- | :----------------------| + | -U | 连接数据库的用户名,需要是MogDB管理员用户。 | -U omm | + | -W | 指定用户连接的密码。
- 如果主机的认证策略是trust,则不会对数据库管理员进行密码验证,即无需输入-W选项;
- 如果没有-W选项,并且不是数据库管理员,会提示用户输入密码。 | -W Bigdata@123 | + | -f | 将导出文件发送至指定目录文件夹。如果这里省略,则使用标准输出。 | -f /home/omm/backup/**MPPDB_tablespace**.sql | + | -p | 指定服务器所监听的TCP端口或本地Unix域套接字后缀,以确保连接。 | -p 8000 | + | -t | 或者-tablespaces-only,只转储表空间,不转储数据库或角色。 | - | + + 其他参数说明请参见《参考指南》中“工具参考 > 服务端工具 > [gs_dumpall](../../../reference-guide/tool-reference/server-tools/6-gs_dumpall.md)”章节。 + +
+ +### 示例 + +示例一: 执行gs_dumpall,导出所有数据库的公共全局表空间信息和用户信息(omm用户为管理员用户),导出文件为文本格式。 + +```bash +gs_dumpall -W Bigdata@123 -U omm -f /home/omm/backup/MPPDB_globals.sql -p 8000 -g +gs_dumpall[port='8000'][2018-11-14 19:06:24]: dumpall operation successful +gs_dumpall[port='8000'][2018-11-14 19:06:24]: total time: 1150 ms +``` + +示例二: 执行gs_dumpall,导出所有数据库的公共全局表空间信息(omm用户为管理员用户),并对导出文件进行加密,导出文件为文本格式。 + +```bash +gs_dumpall -W Bigdata@123 -U omm -f /home/omm/backup/MPPDB_tablespace.sql -p 8000 -t --with-encryption AES128 --with-key 1212121212121212 +gs_dumpall[port='8000'][2018-11-14 19:00:58]: dumpall operation successful +gs_dumpall[port='8000'][2018-11-14 19:00:58]: total time: 186 ms +``` + +示例三: 执行gs_dumpall,导出所有数据库的公共全局用户信息(omm用户为管理员用户),导出文件为文本格式。 + +```bash +gs_dumpall -W Bigdata@123 -U omm -f /home/omm/backup/MPPDB_user.sql -p 8000 -r +gs_dumpall[port='8000'][2018-11-14 19:03:18]: dumpall operation successful +gs_dumpall[port='8000'][2018-11-14 19:03:18]: total time: 162 ms +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/4-data-export-by-a-user-without-required-permissions.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/4-data-export-by-a-user-without-required-permissions.md new file mode 100644 index 00000000..1581a020 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/exporting-data/4-data-export-by-a-user-without-required-permissions.md @@ -0,0 +1,86 @@ +--- +title: 无权限角色导出数据 +summary: 无权限角色导出数据 +author: Guo Huan +date: 2021-03-04 +--- + +# 无权限角色导出数据 + +gs_dump和gs_dumpall通过-U指定执行导出的用户帐户。如果当前使用的帐户不具备导出所要求的权限时,会无法导出数据。此时,需要将有权限的用户赋权给无权限用户,然后可在导出命令中设置-role参数来指定具备权限的角色。在执行命令后,gs_dump和gs_dumpall会使用-role参数指定的角色,完成导出动作。 + +
+ +## 操作步骤 + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用gs_dump导出human_resource数据库数据。 + + 用户jack不具备导出数据库human_resource的权限,而角色role1具备该权限,要实现导出数据库human_resource,需要将role1赋权给jack,然后可以在导出命令中设置-role角色为role1,使用role1的权限,完成导出目的。导出文件格式为tar归档格式。 + + ```bash + gs_dump -U jack -f /home/omm/backup/MPPDB_backup.tar -p 8000 human_resource --role role1 --rolepassword abc@1234 -F t + Password: + ``` + + **表 1** 常用参数说明 + + | 参数 | 参数说明 | 举例 | + | :------- | :----------------------------------------------------------------- | :----------------------| + | -U | 连接数据库的用户名。 | -U jack | + | -W | 指定用户连接的密码。
- 如果主机的认证策略是trust,则不会对数据库管理员进行密码验证,即无需输入-W选项。
- 如果没有-W选项,并且不是数据库管理员,会提示用户输入密码。 | -W Bigdata@123 | + | -f | 将导出文件发送至指定目录文件夹。如果这里省略,则使用标准输出。 | -f /home/omm/backup/MPPDB_backup.tar | + | -p | 指定服务器所监听的TCP端口或本地Unix域套接字后缀,以确保连接。 | -p 8000 | + | dbname | 需要导出的数据库名称 | human_resource | + | -role | 指定导出使用的角色名。选择该选项,会使导出工具连接数据库后,发起一个SET ROLE角色名命令。当所授权用户(由-U指定)没有导出工具要求的权限时,该选项会起到作用,即切换到具备相应权限的角色。 | -r role1 | + | -rolepassword | 指定具体角色用户的角色密码。 | -rolepassword abc@1234 | + | -F | 选择导出文件格式。-F参数值如下:
- p: 纯文本格式
- c: 自定义归档
- d: 目录归档格式
- t: tar归档格式 | -F t | + + 其他参数说明请参见《参考指南》中“工具参考 > 服务端工具 > [gs_dump](../../../reference-guide/tool-reference/server-tools/5-gs_dump.md)”章节或“[gs_dumpall](../../../reference-guide/tool-reference/server-tools/6-gs_dumpall.md)”章节。 + +
+ +## 示例 + +示例一: 执行gs_dump导出数据,用户jack不具备导出数据库human_resource的权限,而角色role1具备该权限,要实现导出数据库human_resource,可以在导出命令中设置-role角色为role1,使用role1的权限,完成导出目的。导出文件格式为tar归档格式。 + +```bash +$ human_resource=# CREATE USER jack IDENTIFIED BY "1234@abc"; +CREATE ROLE +human_resource=# GRANT role1 TO jack; +GRANT ROLE + +$ gs_dump -U jack -f /home/omm/backup/MPPDB_backup11.tar -p 8000 human_resource --role role1 --rolepassword abc@1234 -F t +Password: +gs_dump[port='8000'][human_resource][2017-07-21 16:21:10]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 16:21:10]: total time: 4239 ms +``` + +示例二: 执行gs_dump导出数据,用户jack不具备导出模式public的权限,而角色role1具备该权限,要实现导出模式public,可以在导出命令中设置-role角色为role1,使用role1的权限,完成导出目的。导出文件格式为tar归档格式。 + +```bash +$ human_resource=# CREATE USER jack IDENTIFIED BY "1234@abc"; +CREATE ROLE +human_resource=# GRANT role1 TO jack; +GRANT ROLE + +$ gs_dump -U jack -f /home/omm/backup/MPPDB_backup12.tar -p 8000 human_resource -n public --role role1 --rolepassword abc@1234 -F t +Password: +gs_dump[port='8000'][human_resource][2017-07-21 16:21:10]: dump database human_resource successfully +gs_dump[port='8000'][human_resource][2017-07-21 16:21:10]: total time: 3278 ms +``` + +示例三: 执行gs_dumpall导出数据,用户jack不具备导出所有数据库的权限,而角色role1(管理员)具备该权限,要实现导出所有数据库,可以在导出命令中设置-role角色为role1,使用role1的权限,完成导出目的。导出文件格式为文本归档格式。 + +```bash +$ human_resource=# CREATE USER jack IDENTIFIED BY "1234@abc"; +CREATE ROLE +human_resource=# GRANT role1 TO jack; +GRANT ROLE + +$ gs_dumpall -U jack -f /home/omm/backup/MPPDB_backup.sql -p 8000 --role role1 --rolepassword abc@1234 +Password: +gs_dumpall[port='8000'][human_resource][2018-11-14 17:26:18]: dumpall operation successful +gs_dumpall[port='8000'][human_resource][2018-11-14 17:26:18]: total time: 6437 ms +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/1-import-modes.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/1-import-modes.md new file mode 100644 index 00000000..27ac8cd5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/1-import-modes.md @@ -0,0 +1,18 @@ +--- +title: 导入方式 +summary: 导入方式 +author: Guo Huan +date: 2021-03-04 +--- + +# 导入方式 + +MogDB数据库提供了灵活的数据入库方式: INSERT、COPY以及gsql元命令\\copy。各方式具有不同的特点,具体请参见[表1](#导入方式特点说明)。 + +**表 1** 导入方式特点说明 + +| 方式 | 特点 | +| :--------------------- | :----------------------------------------- | +| INSERT | 通过INSERT语句插入一行或多行数据,及从指定表插入数据。 | +| COPY | 通过COPY FROM STDIN语句直接向MogDB数据库写入数据。
通过JDBC驱动的CopyManager接口从其他数据库向MogDB数据库写入数据时,具有业务数据无需落地成文件的优势。 | +| gsql工具的元命令\\copy | 与直接使用SQL语句COPY不同,该命令读取/写入的文件只能是gsql客户端所在机器上的本地文件。
说明:
\\COPY只适合小批量、格式良好的数据导入,不会对非法字符做预处理,也无容错能力,无法适用于含有异常数据的场景。导入数据应优先选择COPY。 | diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/10-managing-concurrent-write-operations.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/10-managing-concurrent-write-operations.md new file mode 100644 index 00000000..83f11784 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/10-managing-concurrent-write-operations.md @@ -0,0 +1,195 @@ +--- +title: 管理并发写入操作 +summary: 管理并发写入操作 +author: Guo Huan +date: 2021-03-04 +--- + +# 管理并发写入操作 + +
+ +## 事务隔离说明 + +MogDB基于MVCC(多版本并发控制)并结合两阶段锁的方式进行事务管理,其特点是读写之间不阻塞。SELECT是纯读操作,UPDATE和DELETE是读写操作。 + +- 读写操作和纯读操作之间并不会发生冲突,读写操作之间也不会发生冲突。每个并发事务在事务开始时创建事务快照,并发事务之间不能检测到对方的更改。 + + - 读已提交隔离级别中,如果事务T1提交后,事务T2就可以看到事务T1更改的结果。 + + - 可重复读级别中,如果事务T1提交事务前事务T2开始执行,则事务T1提交后,事务T2依旧看不到事务T1更改的结果,保证了一个事务开始后,查询的结果前后一致,不受其他事务的影响。 + +- 读写操作,支持的是行级锁,不同的事务可以并发更新同一个表,只有更新同一行时才需等待,后发生的事务会等待先发生的事务提交后,再执行更新操作。 + + - READ COMMITTED: 读已提交隔离级别,事务只能读到已提交的数据而不会读到未提交的数据,这是缺省值。 + - REPEATABLE READ: 事务只能读到事务开始之前已提交的数据,不能读到未提交的数据以及事务执行期间其它并发事务提交的修改。 + +
+ +## 写入和读写操作 + +关于写入和读写操作的命令: + +- INSERT,可向表中插入一行或多行数据。 +- UPDATE,可修改表中现有数据。 +- DELETE,可删除表中现有数据。 +- COPY,导入数据。 + +INSERT和COPY是纯写入的操作。并发写入操作,需要等待,对同一个表的操作,当事务T1的INSERT或COPY未解除锁定时,事务T2的INSERT或COPY需等待,事务T1解除锁定时,事务T2正常继续。 + +UPDATE和DELETE是读写操作(先查询出要操作的行)。UPDATE和DELETE执行前需要先查询数据,由于并发事务彼此不可见,所以UPDATE和DELETE操作是读取事务发生前提交的数据的快照。写入操作,是行级锁,当事务T1和事务T2并发更新同一行时,后发生的事务T2会等待,根据设置的等待时长,若超时事务T1未提交则事务T2执行失败;当事务T1和事务T2并发更新的行不同时,事务T1和事务2都会执行成功。 + +
+ +## 并发写入事务的潜在死锁情况 + +只要事务涉及多个表的或者同一个表相同行的更新时,同时运行的事务就可能在同时尝试写入时变为死锁状态。事务会在提交或回滚时一次性解除其所有锁定,而不会逐一放弃锁定。 例如,假设事务T1和T2在大致相同的时间开始: + +- 如果T1开始对表A进行写入且T2开始对表B进行写入,则两个事务均可继续而不会发生冲突;但是,如果T1完成了对表A的写入操作并需要开始对表B进行写入,此时操作的行数正好与T2一致,它将无法继续,因为T2仍保持对表B对应行的锁定,此时T2开始更新表A中与T1相同的行数,此时也将无法继续,产生死锁,在锁等待超时内,前面事务提交释放锁,后面的事务可以继续执行更新,等待时间超时后,事务抛错,有一个事务退出。 +- 如果T1,T2都对表A进行写入,此时T1更新1-5行的数据,T2更新6-10行的数据,两个事务不会发生冲突,但是,如果T1完成后开始对表A的6-10行数据进行更新,T2完成后开始更新1-5行的数据,此时两个事务无法继续,在锁等待超时内,前面事务提交释放锁,后面的事务可以继续执行更新,等待时间超时后,事务抛错,有一个事务退出。 + +## 并发写入示例 + +本章节以表test为例,分别介绍相同表的INSERT和DELETE并发,相同表的并发INSERT,相同表的并发UPDATE,以及数据导入和查询的并发的执行详情。 + +```sql +CREATE TABLE test(id int, name char(50), address varchar(255)); +``` + +
+ +### 相同表的INSERT和DELETE并发 + +事务T1: + +```sql +START TRANSACTION; +INSERT INTO test VALUES(1,'test1','test123'); +COMMIT; +``` + +事务T2: + +```sql +START TRANSACTION; +DELETE test WHERE NAME='test1'; +COMMIT; +``` + +场景1: + +开启事务T1,不提交的同时开启事务T2,事务T1执行INSERT完成后,执行事务T2的DELETE,此时显示DELETE 0,由于事务T1未提交,事务2看不到事务插入的数据; + +场景2: + +- READ COMMITTED级别 + + 开启事务T1,不提交的同时开启事务T2,事务T1执行INSERT完成后,提交事务T1,事务T2再执行DELETE语句时,此时显示DELETE 1,事务T1提交完成后,事务T2可以看到此条数据,可以删除成功。 + +- REPEATABLE READ级别 + + 开启事务T1,不提交的同时开启事务T2,事务T1执行INSERT完成后,提交事务T1,事务T2再执行DELETE语句时,此时显示DELETE 0,事务T1提交完成后,事务T2依旧看不到事务T1的数据,一个事务中前后查询到的数据是一致的。 + +
+ +### 相同表的并发INSERT + +事务T1: + +```sql +START TRANSACTION; +INSERT INTO test VALUES(2,'test2','test123'); +COMMIT; +``` + +事务T2: + +```sql +START TRANSACTION; +INSERT INTO test VALUES(3,'test3','test123'); +COMMIT; +``` + +场景1: + +开启事务T1,不提交的同时开启事务T2,事务T1执行INSERT完成后,执行事务T2的INSERT语句,可以执行成功,读已提交和可重复读隔离级别下,此时在事务T1中执行SELECT语句,看不到事务T2中插入的数据,事务T2中执行查询语句看不到事务T1中插入的数据。 + +场景2: + +- READ COMMITTED级别 + + 开启事务T1,不提交的同时开启事务T2,事务T1执行INSERT完成后直接提交,事务T2中执行INSERT语句后执行查询语句,可以看到事务T1中插入的数据。 + +- REPEATABLE READ级别 + + 开启事务T1,不提交的同时开启事务T2,事务T1执行INSERT完成后直接提交,事务T2中执行INSERT语句后执行查询语句,看不到事务T1中插入的数据。 + +
+ +### 相同表的并发UPDATE + +事务T1: + +```sql +START TRANSACTION; +UPDATE test SET address='test1234' WHERE name='test1'; +COMMIT; +``` + +事务T2: + +```sql +START TRANSACTION; +UPDATE test SET address='test1234' WHERE name='test2'; +COMMIT; +``` + +事务T3: + +```sql +START TRANSACTION; +UPDATE test SET address='test1234' WHERE name='test1'; +COMMIT; +``` + +场景1: + +开启事务T1,不提交的同时开启事务T2,事务T1开始执行UPDATE,事务T2开始执行UPDATE,事务T1和事务T2都执行成功。更新不同行时,更新操作拿的是行级锁,不会发生冲突,两个事务都可以执行成功。 + +场景2: + +开启事务T1,不提交的同时开启事务T3,事务T1开始执行UPDATE,事务T3开始执行UPDATE,事务T1执行成功,事务T3等待超时后会出错。更新相同行时,事务T1未提交时,未释放锁,导致事务T3执行不成功。 + +
+ +### 数据导入和查询的并发 + +事务T1: + +```sql +START TRANSACTION; +COPY test FROM '...'; +COMMIT; +``` + +事务T2: + +```sql +START TRANSACTION; +SELECT * FROM test; +COMMIT; +``` + +场景1: + +开启事务T1,不提交的同时开启事务T2,事务T1开始执行COPY,事务T2开始执行SELECT,事务T1和事务T2都执行成功。事务T2中查询看不到事务T1新COPY进来的数据。 + +场景2: + +- READ COMMITTED级别 + + 开启事务T1,不提交的同时开启事务T2,事务T1开始执行COPY,然后提交,事务T2查询,可以看到事务T1中COPY的数据。 + +- REPEATABLE READ级别 + + 开启事务T1,不提交的同时开启事务T2,事务T1开始执行COPY,然后提交,事务T2 查询,看不到事务T1中COPY的数据。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/2-running-the-INSERT-statement-to-insert-data.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/2-running-the-INSERT-statement-to-insert-data.md new file mode 100644 index 00000000..e5f9bd28 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/2-running-the-INSERT-statement-to-insert-data.md @@ -0,0 +1,20 @@ +--- +title: 通过INSERT语句直接写入数据 +summary: 通过INSERT语句直接写入数据 +author: Guo Huan +date: 2021-03-04 +--- + +# 通过INSERT语句直接写入数据 + +用户可以通过以下方式执行INSERT语句直接向MogDB数据库写入数据: + +- 使用MogDB数据库提供的客户端工具向MogDB数据库写入数据。 + + 请参见向表中插入数据。 + +- 通过JDBC/ODBC驱动连接数据库执行INSERT语句向MogDB数据库写入数据。 + + 详细内容请参见连接数据库。 + +MogDB数据库支持完整的数据库事务级别的增删改操作。INSERT是最简单的一种数据写入方式,这种方式适合数据写入量不大,并发度不高的场景。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/3-running-the-COPY-FROM-STDIN-statement-to-import-data.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/3-running-the-COPY-FROM-STDIN-statement-to-import-data.md new file mode 100644 index 00000000..a3aecfcb --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/3-running-the-COPY-FROM-STDIN-statement-to-import-data.md @@ -0,0 +1,318 @@ +--- +title: COPY FROM STDIN导入数据 +summary: COPY FROM STDIN导入数据 +author: Guo Huan +date: 2021-03-04 +--- + +# 使用COPY FROM STDIN导入数据 + +
+ +## 关于COPY FROM STDIN导入数据 + +用户可以使用以下方式通过COPY FROM STDIN语句直接向MogDB写入数据。 + +- 通过键盘输入向MogDB数据库写入数据。详细请参见[COPY](../../../reference-guide/sql-syntax/COPY.md)。 +- 通过JDBC驱动的CopyManager接口从文件或者数据库向MogDB写入数据。此方法支持COPY语法中copy option的所有参数。 + +
+ +## CopyManager类简介 + +CopyManager是MogDB JDBC驱动中提供的一个API接口类,用于批量向MogDB数据库中导入数据。 + +
+ +### CopyManager的继承关系 + +CopyManager类位于org.opengauss.copy Package中,继承自java.lang.Object类,该类的声明如下: + +```java +public class CopyManager +extends Object +``` + +
+ +### 构造方法 + +```java +public CopyManager(BaseConnection connection) +throws SQLException +``` + +
+ +### 常用方法 + +**表 1** CopyManager常用方法 + +| 返回值 | 方法 | 描述 | throws | +| :------ | :-------------------------- | :------------------------------- | :----------------------- | +| CopyIn | copyIn(String sql) | - | SQLException | +| long | copyIn(String sql, InputStream from) | 使用COPY FROM STDIN从InputStream中快速向数据库中的表导入数据。 | SQLException,IOException | +| long | copyIn(String sql, InputStream from, int bufferSize) | 使用COPY FROM STDIN从InputStream中快速向数据库中的表导入数据。 | SQLException,IOException | +| long | copyIn(String sql, Reader from) | 使用COPY FROM STDIN从Reader中快速向数据库中的表导入数据。 | SQLException,IOException | +| long | copyIn(String sql, Reader from, int bufferSize) | 使用COPY FROM STDIN从Reader中快速向数据库中的表导入数据。 | SQLException,IOException | +| CopyOut | copyOut(String sql) | - | SQLException | +| long | copyOut(String sql, OutputStream to) | 将一个COPY TO STDOUT的结果集从数据库发送到OutputStream类中。 | SQLException,IOException | +| long | copyOut(String sql, Writer to) | 将一个COPY TO STDOUT的结果集从数据库发送到Writer类中。 | SQLException,IOException | + +
+ +## 处理错误表 + +### 操作场景 + +当数据导入发生错误时,请根据本文指引信息进行处理。 + +### 查询错误信息 + +数据导入过程中发生的错误,一般分为数据格式错误和非数据格式错误。 + +- 数据格式错误 + + 在创建外表时,通过设置参数“LOG INTO error_table_name”,将数据导入过程中出现的数据格式错误信息写入指定的错误信息表error_table_name中。您可以通过以下SQL,查询详细错误信息。 + + ```sql + MogDB=# SELECT * FROM error_table_name; + ``` + + 错误信息表结构如表1所示。 + + **表 1** 错误信息表 + + | 列名称 | 类型 | 描述 | + | :-------- | :----------------------- | :------------------------------------------- | + | nodeid | integer | 报错节点编号。 | + | begintime | timestamp with time zone | 出现数据格式错误的时间。 | + | filename | character varying | 出现数据格式错误的数据源文件名。 | + | rownum | numeric | 在数据源文件中,出现数据格式错误的行号。 | + | rawrecord | text | 在数据源文件中,出现数据格式错误的原始记录。 | + | detail | text | 详细错误信息。 | + +- 非数据格式错误 + + 对于非数据格式错误,一旦发生将导致整个数据导入失败。您可以根据执行数据导入过程中,界面提示的错误信息,帮助定位问题,处理错误表。 + +### 处理数据导入错误 + +根据获取的错误信息,请对照下表,处理数据导入错误。 + +**表 2** 处理数据导入错误 + +| 错误信息 | 原因 | 解决办法 | +| :----------------------------------------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- | +| missing data for column “r_reason_desc” | 1. 数据源文件中的列数比外表定义的列数少。
2. 对于TEXT格式的数据源文件,由于转义字符(\)导致delimiter(分隔符)错位或者quote(引号字符)错位造成的错误。
**示例:**目标表存在3列字段,导入的数据如下所示。由于存在转义字符“\”,分隔符“\|”被转义为第二个字段的字段值,导致第三个字段值缺失。
`BE|Belgium|1` | 1. 由于列数少导致的报错,选择下列办法解决:
- 在数据源文件中,增加列“r_reason_desc”的字段值。
- 在创建外表时,将参数“fill_missing_fields”设置为“on”。即当导入过程中,若数据源文件中一行数据的最后一个字段缺失,则把最后一个字段的值设置为NULL,不报错。
2. 对由于转义字符导致的错误,需检查报错的行中是否含有转义字符(\)。若存在,建议在创建外表时,将参数“noescaping”(是否不对'\\'和后面的字符进行转义)设置为true。 | +| extra data after last expected column | 数据源文件中的列数比外表定义的列数多。 | - 在数据源文件中,删除多余的字段值。
- 在创建外表时,将参数“ignore_extra_data”设置为“on”。即在导入过程中,若数据源文件比外表定义的列数多,则忽略行尾多出来的列。 | +| invalid input syntax for type numeric: “a” | 数据类型错误。 | 在数据源文件中,修改输入字段的数据类型。根据此错误信息,请将输入的数据类型修改为numeric。 | +| null value in column “staff_id” violates not-null constraint | 非空约束。 | 在数据源文件中,增加非空字段信息。根据此错误信息,请增加“staff_id”列的值。 | +| duplicate key value violates unique constraint “reg_id_pk” | 唯一约束。 | - 删除数据源文件中重复的行。
- 通过设置关键字“DISTINCT”,从SELECT结果集中删除重复的行,保证导入的每一行都是唯一的。
`MogDB=# INSERT INTO reasons SELECT DISTINCT * FROM foreign_tpcds_reasons;` | +| value too long for type character varying(16) | 字段值长度超过限制。 | 在数据源文件中,修改字段值长度。根据此错误信息,字段值长度限制为VARCHAR2(16)。 | + +
+ +## 示例1: 通过本地文件导入导出数据 + +在使用JAVA语言基于MogDB进行二次开发时,可以使用CopyManager接口,通过流方式,将数据库中的数据导出到本地文件或者将本地文件导入数据库中,文件格式支持CSV、TEXT等格式。 + +样例程序如下,执行时需要加载MogDB的JDBC驱动。 + +```java +import java.sql.Connection; +import java.sql.DriverManager; +import java.io.IOException; +import java.io.FileInputStream; +import java.io.FileOutputStream; +import java.sql.SQLException; +import org.opengauss.copy.CopyManager; +import org.opengauss.core.BaseConnection; + +public class Copy{ + + public static void main(String[] args) + { + String urls = new String("jdbc:opengauss://localhost:8000/postgres"); //数据库URL + String username = new String("username"); //用户名 + String password = new String("passwd"); //密码 + String tablename = new String("migration_table"); //定义表信息 + String tablename1 = new String("migration_table_1"); //定义表信息 + String driver = "org.opengauss.Driver"; + Connection conn = null; + + try { + Class.forName(driver); + conn = DriverManager.getConnection(urls, username, password); + } catch (ClassNotFoundException e) { + e.printStackTrace(System.out); + } catch (SQLException e) { + e.printStackTrace(System.out); + } + + // 将表migration_table中数据导出到本地文件d:/data.txt + try { + copyToFile(conn, "d:/data.txt", "(SELECT * FROM migration_table)"); + } catch (SQLException e) { + // TODO Auto-generated catch block + e.printStackTrace(); + } catch (IOException e) { + // TODO Auto-generated catch block + e.printStackTrace(); + } + //将d:/data.txt中的数据导入到migration_table_1中。 + try { + copyFromFile(conn, "d:/data.txt", tablename1); + } catch (SQLException e) { + // TODO Auto-generated catch block + e.printStackTrace(); + } catch (IOException e) { + // TODO Auto-generated catch block + e.printStackTrace(); + } + + // 将表migration_table_1中的数据导出到本地文件d:/data1.txt + try { + copyToFile(conn, "d:/data1.txt", tablename1); + } catch (SQLException e) { + // TODO Auto-generated catch block + e.printStackTrace(); + } catch (IOException e) { + // TODO Auto-generated catch block + e.printStackTrace(); + } + } + + public static void copyFromFile(Connection connection, String filePath, String tableName) + throws SQLException, IOException { + + FileInputStream fileInputStream = null; + + try { + CopyManager copyManager = new CopyManager((BaseConnection)connection); + fileInputStream = new FileInputStream(filePath); + copyManager.copyIn("COPY " + tableName + " FROM STDIN with (" + "DELIMITER"+"'"+ delimiter + "'" + "ENCODING " + "'" + encoding + "')", fileInputStream); + } finally { + if (fileInputStream != null) { + try { + fileInputStream.close(); + } catch (IOException e) { + e.printStackTrace(); + } + } + } + } + public static void copyToFile(Connection connection, String filePath, String tableOrQuery) + throws SQLException, IOException { + + FileOutputStream fileOutputStream = null; + + try { + CopyManager copyManager = new CopyManager((BaseConnection)connection); + fileOutputStream = new FileOutputStream(filePath); + copyManager.copyOut("COPY " + tableOrQuery + " TO STDOUT", fileOutputStream); + } finally { + if (fileOutputStream != null) { + try { + fileOutputStream.close(); + } catch (IOException e) { + e.printStackTrace(); + } + } + } + } +} +``` + +
+ +## 示例2: 从MY向MogDB数据库进行数据迁移 + +下面示例演示如何通过CopyManager从MY向MogDB数据库进行数据迁移的过程。 + +```java +import java.io.StringReader; +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.ResultSet; +import java.sql.SQLException; +import java.sql.Statement; + +import org.opengauss.copy.CopyManager; +import org.opengauss.core.BaseConnection; + +public class Migration{ + + public static void main(String[] args) { + String url = new String("jdbc:opengauss://localhost:8000/postgres"); //数据库URL + String user = new String("username"); //MogDB数据库用户名 + String pass = new String("passwd"); //MogDB数据库密码 + String tablename = new String("migration_table_1"); //定义表信息 + String delimiter = new String("|"); //定义分隔符 + String encoding = new String("UTF8"); //定义字符集 + String driver = "org.opengauss.Driver"; + StringBuffer buffer = new StringBuffer(); //定义存放格式化数据的缓存 + + try { + //获取源数据库查询结果集 + ResultSet rs = getDataSet(); + + //遍历结果集,逐行获取记录 + //将每条记录中各字段值,按指定分隔符分割,由换行符结束,拼成一个字符串 + //把拼成的字符串,添加到缓存buffer + while (rs.next()) { + buffer.append(rs.getString(1) + delimiter + + rs.getString(2) + delimiter + + rs.getString(3) + delimiter + + rs.getString(4) + + "\n"); + } + rs.close(); + + try { + //建立目标数据库连接 + Class.forName(driver); + Connection conn = DriverManager.getConnection(url, user, pass); + BaseConnection baseConn = (BaseConnection) conn; + baseConn.setAutoCommit(false); + + //初始化表信息 + String sql = "Copy " + tablename + " from STDIN with (DELIMITER " + "'" + delimiter + "'" +","+ " ENCODING " + "'" + encoding + "'"); + + //提交缓存buffer中的数据 + CopyManager cp = new CopyManager(baseConn); + StringReader reader = new StringReader(buffer.toString()); + cp.copyIn(sql, reader); + baseConn.commit(); + reader.close(); + baseConn.close(); + } catch (ClassNotFoundException e) { + e.printStackTrace(System.out); + } catch (SQLException e) { + e.printStackTrace(System.out); + } + + } catch (Exception e) { + e.printStackTrace(); + } + } + + //******************************** + // 从源数据库返回查询结果集 + //********************************* + private static ResultSet getDataSet() { + ResultSet rs = null; + try { + Class.forName("com.MY.jdbc.Driver").newInstance(); + Connection conn = DriverManager.getConnection("jdbc:MY://10.119.179.227:3306/jack?useSSL=false&allowPublicKeyRetrieval=true", "jack", "Enmo@123"); + Statement stmt = conn.createStatement(); + rs = stmt.executeQuery("select * from migration_table"); + } catch (SQLException e) { + e.printStackTrace(); + } catch (Exception e) { + e.printStackTrace(); + } + return rs; + } +} +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/4-using-a-gsql-meta-command-to-import-data.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/4-using-a-gsql-meta-command-to-import-data.md new file mode 100644 index 00000000..78047055 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/4-using-a-gsql-meta-command-to-import-data.md @@ -0,0 +1,211 @@ +--- +title: 使用gsql元命令导入数据 +summary: 使用gsql元命令导入数据 +author: Guo Huan +date: 2021-03-04 +--- + +# 使用gsql元命令导入数据 + +gsql工具提供了元命令\\copy进行数据导入。 + +
+ +**\\copy命令** + +## 语法 + +``` +\copy { table [ ( column_list ) ] | + +( query ) } { from | to } { filename | + +stdin | stdout | pstdin | pstdout } + +[ with ] [ binary ] [ delimiter + +[ as ] 'character' ] [ null [ as ] 'string' ] + +[ csv [ header ] [ quote [ as ] + +'character' ] [ escape [ as ] 'character' ] + +[ force quote column_list | * ] [ force + +not null column_list ] ] +``` + +在任何gsql客户端登录数据库成功后,可以使用该命令进行数据的导入/导出。但是与SQL的COPY命令不同,该命令读取/写入的文件是本地文件,而非数据库服务器端文件;所以,要操作的文件的可访问性、权限等,都是受限于本地用户的权限。 + +> **说明**: +> +> \\COPY只适合小批量、格式良好的数据导入,不会对非法字符做预处理,也无容错能力,无法适用于含有异常数据的场景。导入数据应优先选择GDS或COPY。 + +**参数说明** + +- table + + 表的名称(可以有模式修饰)。 + + 取值范围: 已存在的表名。 + +- column_list + + 可选的待拷贝字段列表。 + + 取值范围: 任意字段。如果没有声明字段列表,将使用所有字段。 + +- query + + 其结果将被拷贝。 + + 取值范围: 一个必须用圆括弧包围的SELECT或VALUES命令。 + +- filename + + 文件的绝对路径。执行copy命令的用户必须有此路径的写权限。 + +- stdin + + 声明输入是来自标准输入。 + +- stdout + + 声明输出打印到标准输出。 + +- pstdin + + 声明输入是来自gsql的标准输入。 + +- pstout + +- 声明输出打印到gsql的标准输出。 + +- binary + + 使用二进制格式存储和读取,而不是以文本的方式。在二进制模式下,不能声明DELIMITER,NULL,CSV选项。指定binary类型后,不能再通过option或copy_option指定CSV、FIXED、TEXT等类型。 + +- delimiter [ as ] 'character' + + 指定数据文件行数据的字段分隔符。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > + > - 分隔符不能是\\r和\\n。 + > - 分隔符不能和null参数相同,CSV格式数据的分隔符不能和quote参数相同。 + > - TEXT格式数据的分隔符不能包含: \\.abcdefghijklmnopqrstuvwxyz0123456789。 + > - 数据文件中单行数据长度需<1GB,如果分隔符较长且数据列较多的情况下,会影响导出有效数据的长度。 + > - 分隔符推荐使用多字符和不可见字符。多字符例如'$^&';不可见字符例如0x07,0x08,0x1b等。 + + 取值范围: 支持多字符分隔符,但分隔符不能超过10个字节。 + + 默认值: + + - TEXT格式的默认分隔符是水平制表符(tab)。 + - CSV格式的默认分隔符为","。 + - FIXED格式没有分隔符。 + +- null [ as ] 'string' + + 用来指定数据文件中空值的表示。 + + 取值范围: + + - null值不能是\\r和\\n,最大为100个字符。 + - null值不能和分隔符、quote参数相同。 + + 默认值: + + - CSV格式下默认值是一个没有引号的空字符串。 + - 在TEXT格式下默认值是\\N。 + +- header + + 指定导出数据文件是否包含标题行,标题行一般用来描述表中每个字段的信息。header只能用于CSV,FIXED格式的文件中。 + + 在导入数据时,如果header选项为on,则数据文本第一行会被识别为标题行,会忽略此行。如果header为off,而数据文件中第一行会被识别为数据。 + + 在导出数据时,如果header选项为on,则需要指定fileheader。fileheader是指定导出数据包含标题行的定义文件。如果header为off,则导出数据文件不包含标题行。 + + 取值范围: true/on,false/off。 + + 默认值: false + +- quote [ as ] 'character' + + CSV格式文件下的引号字符。 + + 默认值: 双引号。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > + > - quote参数不能和分隔符、null参数相同。 + > - quote参数只能是单字节的字符。 + > - 推荐不可见字符作为quote,例如0x07,0x08,0x1b等。 + +- escape [ as ] 'character' + + CSV格式下,用来指定逃逸字符,逃逸字符只能指定为单字节字符。 + + 默认值: 双引号。当与quote值相同时,会被替换为'\\0'。 + +- force quote column_list | * + + 在CSV COPY TO模式下,强制在每个声明的字段周围对所有非NULL值都使用引号包围。NULL输出不会被引号包围。 + + 取值范围: 已存在的字段。 + +- force not null column_list + + 在CSV COPY FROM模式下,指定的字段输入不能为空。 + + 取值范围: 已存在的字段。 + +
+ +**任务示例** + +1. 创建目标表a。 + + ```sql + MogDB=# CREATE TABLE a(a int); + ``` + +2. 导入数据。 + + 从stdin拷贝数据到目标表a。 + + ```sql + MogDB=# \copy a from stdin; + ``` + + 出现>>符号提示时,输入数据,输入\\.时结束。 + + ```sql + Enter data to be copied followed by a newline. + End with a backslash and a period on a line by itself. + >> 1 + >> 2 + >> \. + ``` + + 查询导入目标表a的数据。 + + ```sql + MogDB=# SELECT * FROM a; + a + --- + 1 + 2 + (2 rows) + ``` + +3. 从本地文件拷贝数据到目标表a。假设存在本地文件/home/omm/2.csv。 + + - 分隔符为“,”。 + + - 在导入过程中,若数据源文件比外表定义的列数多,则忽略行尾多出来的列。 + + ```sql + MogDB=# \copy a FROM '/home/omm/2.csv' WITH (delimiter',',IGNORE_EXTRA_DATA 'on'); + ``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/5-using-gs_restore-to-import-data.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/5-using-gs_restore-to-import-data.md new file mode 100644 index 00000000..43b8b7e0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/5-using-gs_restore-to-import-data.md @@ -0,0 +1,272 @@ +--- +title: 使用gs_restore命令导入数据 +summary: 使用gs_restore命令导入数据 +author: Guo Huan +date: 2021-03-04 +--- + +# 使用gs_restore命令导入数据 + +
+ +## 操作场景 + +gs_restore是MogDB数据库提供的与gs_dump配套的导入工具。通过该工具,可将gs_dump导出的文件导入至数据库。gs_restore支持导入的文件格式包含自定义归档格式、目录归档格式和tar归档格式。 + +gs_restore具备如下两种功能。 + +- 导入至数据库 + + 如果指定了数据库,则数据将被导入到指定的数据库中。其中,并行导入必须指定连接数据库的密码。导入时生成列会自动更新,并像普通列一样保存。 + +- 导入至脚本文件 + + 如果未指定导入数据库,则创建包含重建数据库所需的SQL语句脚本,并将其写入至文件或者标准输出。该脚本文件等效于gs_dump导出的纯文本格式文件。 + +gs_restore工具在导入时,允许用户选择需要导入的内容,并支持在数据导入前对等待导入的内容进行排序。 + +
+ +## 操作步骤 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** +> gs_restore默认是以追加的方式进行数据导入。为避免多次导入造成数据异常,在进行导入时,建议选择使用"-c" 和"-e"参数。"-c"表示在重新创建数据库对象前,清理(删除)已存在于将要还原的数据库中的数据库对象;"-e"表示当发送SQL语句到数据库时如果出现错误请退出,默认状态下会继续,且在导入后会显示一系列错误信息。 + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用gs_restore命令,从mogdb整个数据库内容的导出文件中,将数据库的所有对象的定义导入到backupdb。 + + ```bash + gs_restore -U jack /home/omm/backup/MPPDB_backup.tar -p 8000 -d backupdb -s -e -c + Password: + ``` + + **表 1** 常用参数说明 + + | 参数 | 参数说明| 举例 | + | :----- | :--------------------| :------------- | + | -U | 连接数据库的用户名。 | -U jack | + | -W | 指定用户连接的密码。
- 如果主机的认证策略是trust,则不会对数据库管理员进行密码验证,即无需输入-W选项;
- 如果没有-W选项,并且不是数据库管理员,会提示用户输入密码。 | -W abcd@123 | + | -d | 连接数据库dbname,并直接将数据导入到该数据库中。 | -d backupdb | + | -p | 指定服务器所监听的TCP端口或本地Unix域套接字后缀,以确保连接。 | -p 8000 | + | -e | 当发送SQL语句到数据库时如果出现错误,则退出。默认状态下会忽略错误任务并继续执行导入,且在导入后会显示一系列错误信息。 | - | + | -c | 在重新创建数据库对象前,清理(删除)已存在于将要导入的数据库中的数据库对象。 | - | + | -s | 只导入模式定义,不导入数据。当前的序列值也不会被导入。 | - | + + 其他参数说明请参见《参考指南》中“工具参考 > 服务端工具 > [gs_restore](../../../reference-guide/tool-reference/server-tools/9-gs_restore.md)”章节。 + +
+ +## 示例 + +示例一:执行gs_restore,导入指定MPPDB_backup.dmp文件(自定义归档格式)中mogdb数据库的数据和对象定义。 + +```bash +gs_restore backup/MPPDB_backup.dmp -p 8000 -d backupdb +gs_restore[2017-07-21 19:16:26]: restore operation successful +gs_restore: total time: 13053 ms +``` + +示例二:执行gs_restore,导入指定MPPDB_backup.tar文件(tar归档格式)中mogdb数据库的数据和对象定义。 + +```bash +gs_restore backup/MPPDB_backup.tar -p 8000 -d backupdb +gs_restore[2017-07-21 19:21:32]: restore operation successful +gs_restore[2017-07-21 19:21:32]: total time: 21203 ms +``` + +示例三:执行gs_restore,导入指定MPPDB_backup目录文件(目录归档格式)中mogdb数据库的数据和对象定义。 + +```bash +gs_restore backup/MPPDB_backup -p 8000 -d backupdb +gs_restore[2017-07-21 19:26:46]: restore operation successful +gs_restore[2017-07-21 19:26:46]: total time: 21003 ms +``` + +示例四:执行gs_restore,将mogdb数据库的所有对象的定义导入至backupdb数据库。导入前,数据库存在完整的定义和数据,导入后,backupdb数据库只存在所有对象定义,表没有数据。 + +```bash +gs_restore /home/omm/backup/MPPDB_backup.tar -p 8000 -d backupdb -s -e -c +gs_restore[2017-07-21 19:46:27]: restore operation successful +gs_restore[2017-07-21 19:46:27]: total time: 32993 ms +``` + +示例五:执行gs_restore,导入MPPDB_backup.dmp文件中PUBLIC模式的所有定义和数据。在导入时会先删除已经存在的对象,如果原对象存在跨模式的依赖则需手工强制干预。 + +```bash +gs_restore backup/MPPDB_backup.dmp -p 8000 -d backupdb -e -c -n PUBLIC +gs_restore: [archiver (db)] Error while PROCESSING TOC: +gs_restore: [archiver (db)] Error from TOC entry 313; 1259 337399 TABLE table1 gaussdba +gs_restore: [archiver (db)] could not execute query: ERROR: cannot drop table table1 because other objects depend on it +DETAIL: view t1.v1 depends on table table1 +HINT: Use DROP ... CASCADE to drop the dependent objects too. +Command was: DROP TABLE public.table1; +``` + +手工删除依赖,导入完成后再重新创建。 + +```bash +gs_restore backup/MPPDB_backup.dmp -p 8000 -d backupdb -e -c -n PUBLIC +gs_restore[2017-07-21 19:52:26]: restore operation successful +gs_restore[2017-07-21 19:52:26]: total time: 2203 ms +``` + +示例六:执行gs_restore,导入MPPDB_backup.dmp文件中hr模式下表hr.staffs的定义。在导入之前,hr.staffs表不存在,需要确保存在hr的schema。 + +```bash +gs_restore backup/MPPDB_backup.dmp -p 8000 -d backupdb -e -c -s -n hr -t staffs +gs_restore[2017-07-21 19:56:29]: restore operation successful +gs_restore[2017-07-21 19:56:29]: total time: 21000 ms +``` + +示例七: 执行gs_restore,导入MPPDB_backup.dmp文件中hr模式下表hr.staffs的数据。在导入之前,hr.staffs表不存在数据,需要确保存在hr的schema。 + +```bash +gs_restore backup/MPPDB_backup.dmp -p 8000 -d backupdb -e -a -n hr -t staffs +gs_restore[2017-07-21 20:12:32]: restore operation successful +gs_restore[2017-07-21 20:12:32]: total time: 20203 ms +``` + +示例八:执行gs_restore,导入指定表hr.staffs的定义。在导入之前,hr.staffs表的数据是存在的。 + +```sql +human_resource=# select * from hr.staffs; + staff_id | first_name | last_name | email | phone_number | hire_date | employment_id | salary | commission_pct | manager_id | section_id +----------+-------------+-------------+----------+--------------------+---------------------+---------------+----------+----------------+------------+------------ + 200 | Jennifer | Whalen | JWHALEN | 515.123.4444 | 1987-09-17 00:00:00 | AD_ASST | 4400.00 | | 101 | 10 + 201 | Michael | Hartstein | MHARTSTE | 515.123.5555 | 1996-02-17 00:00:00 | MK_MAN | 13000.00 | | 100 | 20 + +$ gsql -d human_resource -p 8000 + +gsql ((MogDB x.x.x build 56189e20) compiled at 2022-01-07 18:47:53 commit 0 last mr +Non-SSL connection (SSL connection is recommended when requiring high-security) +Type "help" for help. + +human_resource=# drop table hr.staffs CASCADE; +NOTICE: drop cascades to view hr.staff_details_view +DROP TABLE + +$ gs_restore /home/omm/backup/MPPDB_backup.tar -p 8000 -d human_resource -n hr -t staffs -s -e +Password: +restore operation successful +total time: 904 ms + +human_resource=# select * from hr.staffs; + staff_id | first_name | last_name | email | phone_number | hire_date | employment_id | salary | commission_pct | manager_id | section_id +----------+------------+-----------+-------+--------------+-----------+---------------+--------+----------------+------------+------------ +(0 rows) +``` + +示例九:执行gs_restore,导入staffs和areas两个指定表的定义和数据。在导入之前,staffs和areas表不存在。 + +```sql +human_resource=# \d + List of relations + Schema | Name | Type | Owner | Storage +--------+--------------------+-------+----------+---------------------------------- + hr | employment_history | table | omm | {orientation=row,compression=no} + hr | employments | table | omm | {orientation=row,compression=no} + hr | places | table | omm | {orientation=row,compression=no} + hr | sections | table | omm | {orientation=row,compression=no} + hr | states | table | omm | {orientation=row,compression=no} +(5 rows) + +$ gs_restore /home/mogdb/backup/MPPDB_backup.tar -p 8000 -d human_resource -n hr -t staffs -n hr -t areas +Password: +restore operation successful +total time: 724 ms + +human_resource=# \d + List of relations + Schema | Name | Type | Owner | Storage +--------+--------------------+-------+----------+---------------------------------- + hr | areas | table | omm | {orientation=row,compression=no} + hr | employment_history | table | omm | {orientation=row,compression=no} + hr | employments | table | omm | {orientation=row,compression=no} + hr | places | table | omm | {orientation=row,compression=no} + hr | sections | table | omm | {orientation=row,compression=no} + hr | staffs | table | omm | {orientation=row,compression=no} + hr | states | table | omm | {orientation=row,compression=no} +(7 rows) + +human_resource=# select * from hr.areas; + area_id | area_name +---------+------------------------ + 4 | Middle East and Africa + 1 | Europe + 2 | Americas + 3 | Asia +(4 rows) +``` + +示例十:执行gs_restore,导入hr的模式,包含模式下的所有对象定义和数据。 + +```bash +gs_restore /home/omm/backup/MPPDB_backup1.dmp -p 8000 -d backupdb -n hr -e +Password: +restore operation successful +total time: 702 ms +``` + +示例十一:执行gs_restore,同时导入hr和hr1两个模式,仅导入模式下的所有对象定义。 + +```bash +gs_restore /home/omm/backup/MPPDB_backup2.dmp -p 8000 -d backupdb -n hr -n hr1 -s +Password: +restore operation successful +total time: 665 ms +``` + +示例十二:执行gs_restore,将human_resource数据库导出文件导入至backupdb数据库中。 + +```sql +MogDB=# create database backupdb; +CREATE DATABASE + +$ gs_restore /home/omm/backup/MPPDB_backup.tar -p 8000 -d backupdb + +restore operation successful +total time: 23472 ms + +$ gsql -d backupdb -p 8000 -r + +gsql ((MogDB x.x.x build 56189e20) compiled at 2022-01-07 18:47:53 commit 0 last mr +Non-SSL connection (SSL connection is recommended when requiring high-security) +Type "help" for help. + +backupdb=# select * from hr.areas; + area_id | area_name +---------+------------------------ + 4 | Middle East and Africa + 1 | Europe + 2 | Americas + 3 | Asia +(4 rows) +``` + +示例十三:用户user1不具备将导出文件中数据导入至数据库backupdb的权限,而角色role1具备该权限,要实现将文件数据导入数据库backupdb,可以在导出命令中设置-role角色为role1,使用role1的权限,完成导出目的。 + +```sql +human_resource=# CREATE USER user1 IDENTIFIED BY "1234@abc"; +CREATE ROLE role1 with SYSADMIN IDENTIFIED BY "abc@1234"; + +$ gs_restore -U user1 /home/omm/backup/MPPDB_backup.tar -p 8000 -d backupdb --role role1 --rolepassword abc@1234 +Password: +restore operation successful +total time: 554 ms + +$ gsql -d backupdb -p 8000 -r + +gsql ((MogDB x.x.x build 56189e20) compiled at 2022-01-07 18:47:53 commit 0 last mr +Non-SSL connection (SSL connection is recommended when requiring high-security) +Type "help" for help. + +backupdb=# select * from hr.areas; + area_id | area_name +---------+------------------------ + 4 | Middle East and Africa + 1 | Europe + 2 | Americas + 3 | Asia +(4 rows) +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/6-updating-data-in-a-table.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/6-updating-data-in-a-table.md new file mode 100644 index 00000000..4b7fe6ca --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/6-updating-data-in-a-table.md @@ -0,0 +1,176 @@ +--- +title: 更新表中数据 +summary: 更新表中数据 +author: Guo Huan +date: 2021-03-04 +--- + +# 更新表中数据 + +
+ +## 使用DML命令更新表 + +MogDB支持标准的数据库操作语言(DML)命令,对表进行更新。 + +
+ +### 操作步骤 + +假设存在表customer_t,表结构如下: + +```sql +CREATE TABLE customer_t +( c_customer_sk integer, + c_customer_id char(5), + c_first_name char(6), + c_last_name char(8) +) ; +``` + +可以使用如下DML命令对表进行数据更新。 + +- 使用INSERT向表中插入数据。 + + - 向表customer_t中插入一行。 + + ```sql + INSERT INTO customer_t (c_customer_sk, c_customer_id, c_first_name,c_last_name) VALUES (3769, 5, 'Grace','White'); + ``` + + - 向表customer_t中插入多行数据。 + + ```sql + INSERT INTO customer_t (c_customer_sk, c_customer_id, c_first_name,c_last_name) VALUES + (6885, 1, 'Joes', 'Hunter'), + (4321, 2, 'Lily','Carter'), + (9527, 3, 'James', 'Cook'), + (9500, 4, 'Lucy', 'Baker'); + ``` + + 更多关于INSERT的使用方法,请参见向表中插入数据。 + +- 使用UPDATE更新表中数据。修改字段c_customer_id值为0。 + + ```sql + UPDATE customer_t SET c_customer_id = 0; + ``` + + 更多关于UPDATE的使用方法,请参见UPDATE。 + +- 使用DELETE删除表中的行。 + + 可以使用WHERE子句指定需要删除的行,若不指定即删除表中所有的行,只保留数据结构。 + + ```sql + DELETE FROM customer_t WHERE c_last_name = 'Baker'; + ``` + + 更多关于DELETE的使用方法,请参见DELETE。 + +- 使用TRUNCATE命令快速从表中删除所有的行。 + + ```sql + TRUNCATE TABLE customer_t; + ``` + + 更多关于TRUNCATE的使用方法,请参见TRUNCATE。 + + 删除表时,DELETE语句每次删除一行数据而TRUNCATE语句是通过释放表存储的数据页来删除数据,使用TRUNCATE语句比使用DELETE语句更加快速。 + + 使用DELETE语句删除表时,仅删除数据,不释放存储空间。使用TRUNCATE语句删除表时,删除数据且释放存储空间。 + +
+ +## 使用合并方式更新和插入数据 + +在用户需要将一个表中所有的数据或大量的数据添加至现有表的场景下,MogDB提供了MERGE INTO语句通过两个表合并的方式高效地将新数据添加到现有表。 + +MERGE INTO语句将目标表和源表中数据针对关联条件进行匹配,若关联条件匹配时对目标表进行UPDATE,关联条件不匹配时对目标表执行INSERT。此方法可以很方便地用来将两个表合并执行UPDATE和INSERT,避免多次执行。 + +
+ +### 前提条件 + +进行MERGE INTO操作的用户需要同时拥有目标表的UPDATE和INSERT权限,以及源表的SELECT权限。 + +
+ +### 操作步骤 + +1. 创建源表products,并插入数据。 + + ```sql + MogDB=# CREATE TABLE products + ( product_id INTEGER, + product_name VARCHAR2(60), + category VARCHAR2(60) + ); + + MogDB=# INSERT INTO products VALUES + (1502, 'olympus camera', 'electrncs'), + (1601, 'lamaze', 'toys'), + (1666, 'harry potter', 'toys'), + (1700, 'wait interface', 'books'); + ``` + +2. 创建目标表newproducts,并插入数据。 + + ```sql + MogDB=# CREATE TABLE newproducts + ( product_id INTEGER, + product_name VARCHAR2(60), + category VARCHAR2(60) + ); + + MogDB=# INSERT INTO newproducts VALUES + (1501, 'vivitar 35mm', 'electrncs'), + (1502, 'olympus ', 'electrncs'), + (1600, 'play gym', 'toys'), + (1601, 'lamaze', 'toys'), + (1666, 'harry potter', 'dvd'); + ``` + +3. 使用MERGE INTO 语句将源表products的数据合并至目标表newproducts。 + + ```sql + MERGE INTO newproducts np + USING products p + ON (np.product_id = p.product_id ) + WHEN MATCHED THEN + UPDATE SET np.product_name = p.product_name, np.category = p.category + WHEN NOT MATCHED THEN + INSERT VALUES (p.product_id, p.product_name, p.category) ; + ``` + + 上述语句中使用的参数说明,请见[表1](#MERGE INTO语句参数说明)。更多信息,请参见MERGE INTO。 + + **表 1** MERGE INTO语句参数说明 + + | 参数 | 说明| 举例 | + | :--------------- | :------------- | :--------------| + | INTO 子句 | 指定需要更新或插入数据的目标表。
目标表支持指定别名。 | **取值:**newproducts np
**说明:**名为newproducts,别名为np的目标表。 | + | USING子句 | 指定源表。源表支持指定别名。 | **取值:**products p
**说明:**名为products,别名为p的源表。 | + | ON子句 | 指定目标表和源表的关联条件。
关联条件中的字段不支持更新。 | **取值:**np.product_id = p.product_id
**说明:**指定的关联条件为,目标表newproducts的product_id字段和源表products的product_id字段相等。 | + | WHEN MATCHED子句 | 当源表和目标表中数据针对关联条件可以匹配上时,选择WHEN MATCHED子句进行UPDATE操作。
- 仅支持指定一个WHEN MATCHED子句。
- WHEN MATCHED子句可缺省,缺省时,对于满足ON子句条件的行,不进行任何操作。
- 若目标表中存在分布列,则该列不支持更新。 | **取值:**WHEN MATCHED THEN UPDATE SET np.product_name = p.product_name, np.category = p.category
**说明:**当满足ON子句条件时,将目标表newproducts的product_name、category字段的值替换为源表products相对应字段的值。 | + | WHEN NOT MATCHED子句 | 当源表和目标表中数据针对关联条件无法匹配时,选择WHEN NOT MATCHED子句进行INSERT操作。
- 仅支持指定一个WHEN NOT MATCHED子句。
- WHEN NOT MATCHED子句可缺省。
- 不支持INSERT子句中包含多个VALUES。
- WHEN MATCHED和WHEN NOT MATCHED子 句顺序可以交换,可以缺省其中一个,但不能同时缺省。 | **取值:**WHEN NOT MATCHED THENINSERT VALUES (p.product_id, p.product_name, p.category)
**说明:**将源表products中,不满足ON子句条件的行插入目标表newproducts。 | + +4. 查询合并后的目标表newproducts。 + + ```sql + SELECT * FROM newproducts; + ``` + + 返回信息如下: + + ```sql + product_id | product_name | category + ------------+----------------+----------- + 1501 | vivitar 35mm | electrncs + 1502 | olympus camera | electrncs + 1666 | harry potter | toys + 1600 | play gym | toys + 1601 | lamaze | toys + 1700 | wait interface | books + (6 rows) + ``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/7-deep-copy.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/7-deep-copy.md new file mode 100644 index 00000000..4eee9077 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/7-deep-copy.md @@ -0,0 +1,122 @@ +--- +title: 深层复制 +summary: 深层复制 +author: Guo Huan +date: 2021-03-04 +--- + +# 深层复制 + +数据导入后,如果需要修改表的分区键、或者将行存表改列存、添加PCK(Partial Cluster Key)约束等场景下,可以使用深层复制的方式对表进行调整。深层复制是指重新创建表,然后使用批量插入填充表的过程。 + +Mog提供了三种深层复制的方式供用户选择。 + +
+ +## 使用CREATE TABLE执行深层复制 + +该方法使用CREATE TABLE语句创建原始表的副本,将原始表的数据填充至副本并重命名副本,完成原始表的复制。 + +在创建新表时,可以指定表以及列属性,比如主键。 + +**操作步骤** + +执行如下步骤对表customer_t进行深层复制。 + +1. 使用CREATE TABLE语句创建表customer_t的副本customer_t_copy。 + + ```sql + CREATE TABLE customer_t_copy + ( c_customer_sk integer, + c_customer_id char(5), + c_first_name char(6), + c_last_name char(8) + ) ; + ``` + +2. 使用INSERT INTO…SELECT语句向副本填充原始表中的数据。 + + ```sql + INSERT INTO customer_t_copy (SELECT * FROM customer_t); + ``` + +3. 删除原始表。 + + ```sql + DROP TABLE customer_t; + ``` + +4. 使用ALTER TABLE语句将副本重命名为原始表名称。 + + ```sql + ALTER TABLE customer_t_copy RENAME TO customer_t; + ``` + +
+ +## 使用CREATE TABLE LIKE执行深层复制 + +该方法使用CREATE TABLE LIKE语句创建原始表的副本,将原始表的数据填充至副本并重命名副本,完成原始表的复制。该方法不继承父表的主键属性,您可以使用ALTER TABLE语句来添加它们。 + +**操作步骤** + +1. 使用CREATE TABLE LIKE语句创建表customer_t的副本customer_t_copy。 + + ```sql + CREATE TABLE customer_t_copy (LIKE customer_t); + ``` + +2. 使用INSERT INTO…SELECT语句向副本填充原始表中的数据。 + + ```sql + INSERT INTO customer_t_copy (SELECT * FROM customer_t); + ``` + +3. 删除原始表。 + + ```sql + DROP TABLE customer_t; + ``` + +4. 使用ALTER TABLE语句将副本重命名为原始表名称。 + + ```sql + ALTER TABLE customer_t_copy RENAME TO customer_t; + ``` + +
+ +## 通过创建临时表并截断原始表来执行深层复制 + +该方法使用CREATE TABLE AS语句创建原始表的临时表,然后截断原始表并从临时表填充它完成原始表的深层复制。 + +在新建表需要保留父表的主键属性,或如果父表具有依赖项的情况下,建议使用此方法。 + +**操作步骤** + +1. 使用CREATE TABLE AS语句创建表customer_t的临时表副本customer_t_temp。 + + ```sql + CREATE TEMP TABLE customer_t_temp AS SELECT * FROM customer_t; + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > 与使用永久表相比,使用临时表可以提高性能,但存在丢失数据的风险。临时表只在当前会话可见,本会话结束后将自动删除。如果数据丢失是不可接受的,请使用永久表。 + +2. 截断当前表customer_t。 + + ```sql + TRUNCATE customer_t; + ``` + +3. 使用INSERT INTO…SELECT语句从副本中向原始表中填充数据。 + + ```sql + INSERT INTO customer_t (SELECT * FROM customer_t_temp); + ``` + +4. 删除临时表副本customer_t_temp。 + + ```sql + DROP TABLE customer_t_temp; + ``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/8-ANALYZE-table.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/8-ANALYZE-table.md new file mode 100644 index 00000000..c0a83e74 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/8-ANALYZE-table.md @@ -0,0 +1,50 @@ +--- +title: 分析表 +summary: 分析表 +author: Guo Huan +date: 2021-03-04 +--- + +# 分析表 + +执行计划生成器需要使用表的统计信息,以生成最有效的查询执行计划,提高查询性能。因此数据导入完成后,建议执行ANALYZE语句生成最新的表统计信息。统计结果存储在系统表PG_STATISTIC中。 + +
+ +## 分析表 + +ANALYZE支持的表类型有行/列存表。ANALYZE同时也支持对本地表的指定列进行信息统计。下面以表的ANALYZE为例,更多关于ANALYZE的信息,请参见[ANALYZE | ANALYSE](../../../reference-guide/sql-syntax/ANALYZE-ANALYSE.md)。 + +更新表统计信息。 + +以表product_info为例,ANALYZE命令如下: + +```sql +ANALYZE product_info; +``` + +```sql +ANALYZE +``` + +
+ +## 表自动分析 + +MogDB提供了GUC参数autovacuum用于控制数据库自动清理功能的启动。 + +autovacuum设置为on时,系统定时启动autovacuum线程来进行表自动分析,如果表中数据量发生较大变化达到阈值时,会触发表自动分析,即autoanalyze。 + +- 对于空表而言,当表中插入数据的行数大于50时,会触发表自动进行ANALYZE。 +- 对于表中已有数据的情况,阈值设定为50+10%*reltuples,其中reltuples是表的总行数。 + +autovacuum自动清理功能的生效还依赖于下面两个GUC参数: + +- track_counts 参数需要设置为on,表示开启收集收据库统计数据功能。 +- autovacuum_max_workers参数需要大于0,该参数表示能同时运行的自动清理线程的最大数量。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知:** +> +> - autoanalyze只支持默认采样方式,不支持百分比采样方式。 +> - 多列统计信息仅支持百分比采样,因此autoanalyze不收集多列统计信息。 +> - autoanalyze支持行存表和列存表,不支持外表、临时表、unlogged表和toast表。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/9-doing-VACUUM-to-a-table.md b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/9-doing-VACUUM-to-a-table.md new file mode 100644 index 00000000..7eba6716 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/importing-and-exporting-data/importing-data/9-doing-VACUUM-to-a-table.md @@ -0,0 +1,22 @@ +--- +title: 对表执行VACUUM +summary: 对表执行VACUUM +author: Guo Huan +date: 2021-03-04 +--- + +# 对表执行VACUUM + +如果导入过程中,进行了大量的更新或删除行时,应运行VACUUM FULL命令,然后运行ANALYZE命令。大量的更新和删除操作,会产生大量的磁盘页面碎片,从而逐渐降低查询的效率。VACUUM FULL可以将磁盘页面碎片恢复并交还操作系统。 + +对表执行VACUUM FULL。 + +以表product_info为例,VACUUM FULL命令如下: + +```sql +VACUUM FULL product_info +``` + +```sql +VACUUM +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/localization/character-set-support.md b/product/zh/docs-mogdb/v3.1/administrator-guide/localization/character-set-support.md new file mode 100644 index 00000000..1f4307c4 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/localization/character-set-support.md @@ -0,0 +1,206 @@ +--- +title: 字符集支持 +summary: 字符集支持 +author: Guo Huan +date: 2022-07-26 +--- + +# 字符集支持 + +MogDB支持以各种字符集(也称为编码)存储文本,包含单字节字符集,比如ISO-8859系列,和多字节字符集,比如EUC(扩展Unix编码)、UTF-8、Mule国际编码。所有支持的字符集都可以被客户端透明地使用,但有一些不支持在服务器内使用(即作为服务器端的编码)。缺省字符集是在使用`gs_initdb`初始化数据库集群时选择的。创建数据库时可以重写此缺省值。因此,您可以创建多个具有不同字符集的数据库。 + +但是,存在一个重要的限制,每个数据库的字符集必须与该数据库的`LC_CTYPE`(字符类别)以及 `LC_COLLATE`(字符串排序顺序)区域设置相兼容。对于`C`或者 `POSIX`区域,允许使用任意字符集, 但对于其他区域则只有设置某一个字符集时能正常运行。(不过在Windows上,UTF-8编码可用于任何区域。) + +## 支持的字符集 + +表1显示了可以在MogDB中使用的字符集。 + +**表1 MogDB字符集** + +| 名称 | 描述 | 语言 | 服务器端是否支持 | 字节数/字符 | 别名 | +| ---------------- | --------------------------- | -------------------------- | ---------------- | ----------- | --------------------------------------------- | +| `BIG5` | 大五码 | 繁体中文 | 否 | 1-2 | `WIN950`, `Windows950` | +| `EUC_CN` | 扩展UNIX代码-CN | 简体中文 | 是 | 1-3 | | +| `EUC_JP` | 扩展UNIX代码-JP | 日文 | 是 | 1-3 | | +| `EUC_JIS_2004` | 扩展UNIX代码-JP, JIS X 0213 | 日文 | 是 | 1-3 | | +| `EUC_KR` | 扩展UNIX代码-KR | 韩文 | 是 | 1-3 | | +| `EUC_TW` | 扩展UNIX代码-TW | 繁体中文,台湾 | 是 | 1-3 | | +| `GB18030` | 国标码 | 中文 | 是 | 1-2 | | +| `GBK` | 扩展国标码 | 简体中文 | 是 | 1-2 | `WIN936`, `Windows936` | +| `ISO_8859_5` | ISO 8859-5, ECMA 113 | 拉丁/西里尔语 | 是 | 1 | | +| `ISO_8859_6` | ISO 8859-6, ECMA 114 | 拉丁/阿拉伯语 | 是 | 1 | | +| `ISO_8859_7` | ISO 8859-7, ECMA 118 | 拉丁/希腊语 | 是 | 1 | | +| `ISO_8859_8` | ISO 8859-8, ECMA 121 | 拉丁/希伯莱语 | 是 | 1 | | +| `JOHAB` | JOHAB | 韩语 | 否 | 1-3 | | +| `KOI8R` | KOI8-R | 西里尔语(俄国) | 是 | 1 | `KOI8` | +| `KOI8U` | KOI8-U | 西里尔语(乌克兰) | 是 | 1 | | +| `LATIN1` | ISO 8859-1, ECMA 94 | 西欧语 | 是 | 1 | `ISO88591` | +| `LATIN2` | ISO 8859-2, ECMA 94 | 中欧语 | 是 | 1 | `ISO88592` | +| `LATIN3` | ISO 8859-3, ECMA 94 | 南欧语 | 是 | 1 | `ISO88593` | +| `LATIN4` | ISO 8859-4, ECMA 94 | 北欧语 | 是 | 1 | `ISO88594` | +| `LATIN5` | ISO 8859-9, ECMA 128 | 土耳其语 | 是 | 1 | `ISO88599` | +| `LATIN6` | ISO 8859-10, ECMA 144 | 日耳曼语 | 是 | 1 | `ISO885910` | +| `LATIN7` | ISO 8859-13 | 波罗的海语 | 是 | 1 | `ISO885913` | +| `LATIN8` | ISO 8859-14 | 凯尔特语 | 是 | 1 | `ISO885914` | +| `LATIN9` | ISO 8859-15 | 带有欧洲语系和语调的LATIN1 | 是 | 1 | `ISO885915` | +| `LATIN10` | ISO 8859-16, ASRO SR 14111 | 罗马尼亚语 | 是 | 1 | `ISO885916` | +| `MULE_INTERNAL` | Mule internal code | 多语种Emacs | 是 | 1-4 | | +| `SJIS` | Shift JIS | 日语 | 否 | 1-2 | `Mskanji`, `ShiftJIS`, `WIN932`, `Windows932` | +| `SHIFT_JIS_2004` | Shift JIS, JIS X 0213 | 日语 | 否 | 1-2 | | +| `SQL_ASCII` | unspecified (see text) | **任意** | 是 | 1 | | +| `UHC` | Unified Hangul Code | 韩语 | 否 | 1-2 | `WIN949`, `Windows949` | +| `UTF8` | Unicode, 8-bit | **全部** | 是 | 1-4 | `Unicode` | +| `WIN866` | Windows CP866 | 西里尔语 | 是 | 1 | `ALT` | +| `WIN874` | Windows CP874 | 泰国语 | 是 | 1 | | +| `WIN1250` | Windows CP1250 | 中欧语 | 是 | 1 | | +| `WIN1251` | Windows CP1251 | 西里尔语 | 是 | 1 | `WIN` | +| `WIN1252` | Windows CP1252 | 西欧语 | 是 | 1 | | +| `WIN1253` | Windows CP1253 | 希腊语 | 是 | 1 | | +| `WIN1254` | Windows CP1254 | 土耳其语 | 是 | 1 | | +| `WIN1255` | Windows CP1255 | 希伯来语 | 是 | 1 | | +| `WIN1256` | Windows CP1256 | 阿拉伯语 | 是 | 1 | | +| `WIN1257` | Windows CP1257 | 波罗的语 | 是 | 1 | | +| `WIN1258` | Windows CP1258 | 越南语 | 是 | 1 | `ABC`, `TCVN`, `TCVN5712`, `VSCII` | + +并非所有API都支持上面列出的编码。`SQL_ASCII`设置与其它设置不同。如果服务器字符集是`SQL_ASCII`,服务器根据ASCII标准解析0-127的字节值,而字节值为128-255的则当作未解析的字符。如果设置为`SQL_ASCII`就不会有编码转换。因此,这个设置基本不用来声明所使用的编码,因为此声明会忽略编码。在大多数情况下,如果使用了任何非ASCII数据,那么我们不建议使用`SQL_ASCII`,因为MogDB无法转换或者校验非ASCII字符。 + +## 设置字符集 + +`gs_initdb`可以为一个MogDB集群定义缺省字符集(编码),详细说明请参见[gs_initdb](../../reference-guide/tool-reference/tools-used-in-the-internal-system/5-gs_initdb.md)。 + +您也可以通过SQL语句在数据库创建时指定非缺省编码,但是指定的编码必须与所选的区域相兼容: + +```sql +CREATE DATABASE chinese WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF8' LC_CTYPE='en_US.UTF8' TEMPLATE=template0; +``` + +注意上述命令声明拷贝`template0`数据库。当拷贝任何其他数据库时,来自源数据库的编码和区域设置不能被改变,因为可能导致数据损坏。参阅[CREATE DATABASE](../../reference-guide/sql-syntax/CREATE-DATABASE.md)获取更多信息。 + +数据库的编码存储在`pg_database`系统表中。您可以使用`gsql`的`-l`选项或`\l` 命令列出这些编码。 + +```bash +$ gsql -l + List of databases + Name | Owner | Encoding | Collate | Ctype | Access privileges +-----------+-------+----------+-------------+-------------+------------------- + chinese | omm | UTF8 | en_US.UTF8 | en_US.UTF8 | + mogdb | omm | UTF8 | en_US.UTF-8 | en_US.UTF-8 | + mogila | omm | UTF8 | en_US.UTF-8 | en_US.UTF-8 | + postgres | omm | UTF8 | en_US.UTF-8 | en_US.UTF-8 | + template0 | omm | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =c/omm + + | | | | | omm=CTc/omm + template1 | omm | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =c/omm + + | | | | | omm=CTc/omm +(6 rows) +``` + +> **注意**:在大多数现代操作系统中,MogDB可以通过`LC_CTYPE`的设置决定使用哪种字符集,并且强制只使用匹配的数据库编码。在旧的操作系统上您需要确保使用所选区域所期望的编码。如果设置不正确很可能导致与区域相关的操作表现异常,比如排序。 +> +> 当`LC_CTYPE`不是`C`或者`POSIX`时,MogDB也允许超级用户创建使用`SQL_ASCII`编码的数据库。如上所述,`SQL_ASCII`不强制要求存储在数据库中的数据具有任何特定的编码,因此会存在出现区域相关错误行为的风险。我们不建议使用这样的设置组合,未来版本也许会完全禁止。 + +## 服务器和客户端之间的自动字符集转换 + +MogDB支持在服务器和客户端之间的自动字符集转换。转换信息存储在系统表`pg_conversion`中。MogDB自带一些预定义的转换,如表2所示。 + +**表2 客户端/服务器字符集转换** + +| 服务器端字符集 | 可用的客户端字符集 | +| --------------- | ------------------------------------------------------------ | +| `BIG5` | **不支持做服务器端编码** | +| `EUC_CN` | **EUC_CN**, `MULE_INTERNAL`, `UTF8` | +| `EUC_JP` | **EUC_JP**, `MULE_INTERNAL`, `SJIS`, `UTF8` | +| `EUC_KR` | **EUC_KR**, `MULE_INTERNAL`, `UTF8` | +| `EUC_TW` | **EUC_TW**, `BIG5`, `MULE_INTERNAL`, `UTF8` | +| `GB18030` | **不支持做服务器端编码** | +| `GBK` | **不支持做服务器端编码** | +| `ISO_8859_5` | **ISO_8859_5**, `KOI8R`, `MULE_INTERNAL`, `UTF8`, `WIN866`, `WIN1251` | +| `ISO_8859_6` | **ISO_8859_6**, `UTF8` | +| `ISO_8859_7` | **ISO_8859_7**, `UTF8` | +| `ISO_8859_8` | **ISO_8859_8**, `UTF8` | +| `JOHAB` | **JOHAB**, `UTF8` | +| `KOI8R` | **KOI8R**, `ISO_8859_5`, `MULE_INTERNAL`, `UTF8`, `WIN866`, `WIN1251` | +| `KOI8U` | **KOI8U**, `UTF8` | +| `LATIN1` | **LATIN1**, `MULE_INTERNAL`, `UTF8` | +| `LATIN2` | **LATIN2**, `MULE_INTERNAL`, `UTF8`, `WIN1250` | +| `LATIN3` | **LATIN3**, `MULE_INTERNAL`, `UTF8` | +| `LATIN4` | **LATIN4**, `MULE_INTERNAL`, `UTF8` | +| `LATIN5` | **LATIN5**, `UTF8` | +| `LATIN6` | **LATIN6**, `UTF8` | +| `LATIN7` | **LATIN7**, `UTF8` | +| `LATIN8` | **LATIN8**, `UTF8` | +| `LATIN9` | **LATIN9**, `UTF8` | +| `LATIN10` | **LATIN10**, `UTF8` | +| `MULE_INTERNAL` | **MULE_INTERNAL**, `BIG5`, `EUC_CN`, `EUC_JP`, `EUC_KR`, `EUC_TW`, `ISO_8859_5`, `KOI8R`, `LATIN1` to `LATIN4`, `SJIS`, `WIN866`, `WIN1250`, `WIN1251` | +| `SJIS` | **不支持做服务器端编码** | +| `SQL_ASCII` | **任意(不会发生编码转换)** | +| `UHC` | **不支持做服务器端编码** | +| `UTF8` | **所有支持的编码** | +| `WIN866` | **WIN866**, `ISO_8859_5`, `KOI8R`, `MULE_INTERNAL`, `UTF8`, `WIN1251` | +| `WIN874` | **WIN874**, `UTF8` | +| `WIN1250` | **WIN1250**, `LATIN2`, `MULE_INTERNAL`, `UTF8` | +| `WIN1251` | **WIN1251**, `ISO_8859_5`, `KOI8R`, `MULE_INTERNAL`, `UTF8`, `WIN866` | +| `WIN1252` | **WIN1252**, `UTF8` | +| `WIN1253` | **WIN1253**, `UTF8` | +| `WIN1254` | **WIN1254**, `UTF8` | +| `WIN1255` | **WIN1255**, `UTF8` | +| `WIN1256` | **WIN1256**, `UTF8` | +| `WIN1257` | **WIN1257**, `UTF8` | +| `WIN1258` | **WIN1258**, `UTF8` | + +要打开自动字符集转换功能,您必须键入想在客户端使用的字符集(编码)。 可以通过以下几种方法来实现。 + +- 用gsql里的`\encoding`命令。 `\encoding`允许动态修改客户端编码。 比如,把编码改变为`SJIS`,键入: + + ```sql + \encoding SJIS + ``` + +- 使用[libpq函数](../../developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/1-database-connection-control-functions-overview.md)控制客户端编码。 + +- 使用`SET client_encoding TO`语句。使用下面的SQL命令设置客户端编码: + + ```bash + SET CLIENT_ENCODING TO 'value'; + ``` + + 您也可以使用标准SQL语法`SET NAMES`: + + ```bash + SET NAMES 'value'; + ``` + + 查询当前客户端编码: + + ```bash + SHOW client_encoding; + ``` + + 重置默认编码: + + ```bash + RESET client_encoding; + ``` + +- 使用`PGCLIENTENCODING`。如果在客户端环境里定义了 `PGCLIENTENCODING`环境变量,那么在与服务器进行连接时将自动选择这个客户端编码。此编码可以用上文介绍的方法重写。 + +- 使用[client_encoding](../../reference-guide/guc-parameters/15-default-settings-of-client-connection/2-zone-and-formatting.md#client_encoding)配置变量。 如果在`client_encoding`里设置了该变量, 那么在与服务器建立了连接之后,将自动选定这个客户端编码。此设置可以用上文介绍的方法重写。 + +如果无法进行特定的字符转换,比如,所选的服务器编码是`EUC_JP`而客户端是`LATIN1`,那么部分日文字符无法转换,此时将会报错。 + +如果客户端字符集定义成了`SQL_ASCII`, 那么编码转换会被禁用,无论服务器字符集设置如何。和服务器一样,除非您的业务环境全部使用ASCII数据,否则不建议使用`SQL_ASCII`。 + +## 进一步阅读 + +您可以查阅以下资料了解各种类型的编码系统。 + +- *CJKV Information Processing: Chinese, Japanese, Korean & Vietnamese Computing* + + 包含`EUC_JP`, `EUC_CN`, `EUC_KR`, `EUC_TW`的详细说明。 + +- [http://www.unicode.org/](http://www.unicode.org/) + + Unicode主页。 + +- RFC 3629 + + UTF-8(8-bit UCS/Unicode转换格式)的定义。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/localization/collation-support.md b/product/zh/docs-mogdb/v3.1/administrator-guide/localization/collation-support.md new file mode 100644 index 00000000..3d9dc54c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/localization/collation-support.md @@ -0,0 +1,128 @@ +--- +title: 排序规则支持 +summary: 排序规则支持 +author: Zhang Cuiping +date: 2022-07-26 +--- + +# 排序规则支持 + +排序规则特性允许为每一列数据或者每个操作指定排序顺序和字符分类行为。 这缓解了`LC_COLLATE`和`LC_CTYPE`在数据库创建后不能被修改的限制。 + +## 概念 + +从概念上讲,collatable数据类型的每个表达式都有一个排序规则。 (内置collatable数据类型有`text`, `varchar`以及`char`。 用户定义的基本类型,也可以标记为可排序的, 当然一个可排序的数据类型的域也是可排序的)。 如果表达式是一个列引用,该表达式的排序规则是就这个列的排序规则。 如果表达式是一个常数,排序规则是常数数据类型的缺省排序规则。 一个更复杂表达式的排序规则从它的输入端排序规则推导,如下所述。 + +一个表达式的排序规则可以是"默认"排序规则, 它表示数据库的区域设置。一个表达式的排序规则也可能是不确定的。在这种情况下,排序操作和其他需要知道排序规则的操作会失败。 + +当数据库系统必须执行排序或字符分类时,它使用输入表达式的排序规则。 这会在使用例如`ORDER BY`子句以及函数或操作符调用(如`<`)时发生。 应用到`ORDER BY`子句中的排序规则直接就是排序关键字的排序规则。 应用到函数或操作符调用的排序规则要从参数上派生, 如下文所述。除比较操作符之外,在大小写字母之间转换的函数会考虑排序规则,例如`lower`、`upper`和`initcap`。模式匹配操作符和`to_char`及相关函数也会考虑排序规则。 + +对于一个函数或操作符调用, 其排序规则通过检查在执行指定操作时参数的排序规则来获得。 如果该函数或操作符调用的结果是一种可排序的数据类型,万一有外围表达式要求函数或操作符表达式的排序规则,在解析时结果的排序规则也会被用作函数或操作符表达式的排序规则。 + +一个表达式的*排序规则派生*可以是显式或隐式。该区别会影响多个不同的排序规则出现在同一个表达式中时如何组合它们。当使用一个`COLLATE`子句时,将发生显式排序规则派生。所有其他排序规则派生都是隐式的。当多个排序规则需要被组合时(例如在一个函数调用中),将使用下面的规则: + +1. 如果任何一个输入表达式具有一个显式排序规则派生,则在输入表达式之间的所有显式派生的排序规则必须相同,否则将产生一个错误。如果任何一个显式派生的排序规则存在,它就是排序规则组合的结果。 +2. 否则,所有输入表达式必须具有相同的隐式排序规则派生或默认排序规则。如果任何一个非默认排序规则存在,它就是排序规则组合的结果。否则,结果是默认排序规则。 +3. 如果在输入表达式之间存在冲突的非默认隐式排序规则,则组合被认为是具有不确定排序规则。这并非一种错误情况,除非被调用的特定函数要求提供排序规则。 如果是这样,在运行时将引发一个错误。 + +例如,创建下表: + +```sql +CREATE TABLE test1 ( + a text COLLATE "de_DE", + b text COLLATE "es_ES", + ... +); +``` + +然后 + +```sql +SELECT a < 'foo' FROM test1; +``` + +按照`de_DE`规则,执行`<`比较,因为表达式包含隐式推导排序规则与缺省排序规则,但是 + +```sql +SELECT a < ('foo' COLLATE "fr_FR") FROM test1; +``` + +使用`fr_FR`规则执行比较时,因为显式排序规则覆盖了隐式的。 此外, + +```sql +SELECT a < b FROM test1; +``` + +解析器无法确定应该应用哪个排序规则,因为 `a`列和`b`列拥有冲突的隐式排序规则。 因为`<`操作符确实需要知道所使用的排序规则,这将导致一个错误。 该错误可以通过在一个输入表达式上附加一个显式排序规则说明符来解决,因此: + +```sql +SELECT a < b COLLATE "de_DE" FROM test1; +``` + +或者 + +```sql +SELECT a COLLATE "de_DE" < b FROM test1; +``` + +另一方面,结构上类似的情况 + +```sql +SELECT a || b FROM test1; +``` + +不会产生错误,因为`||`操作符并不关心排序规则: 不论什么排序规则结果都是一样的。 + +如果函数或者操作符的结果还是可排序的数据类型, 那么分配给函数或者操作符的组合的输入表达式的排序规则也会应用到函数或者操作符结果上。 因此, + +```sql +SELECT * FROM test1 ORDER BY a || 'foo'; +``` + +按照`de_DE`规则执行该排序。但是这个查询: + +```sql +SELECT * FROM test1 ORDER BY a || b; +``` + +导致一个错误,因为即使`||`操作符不需要知道排序规则,而`ORDER BY`子句 确实需要。和前面一样,可以使用显式的排序规则说明符解决这个冲突。 + +```sql +SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; +``` + +## 管理排序规则 + +排序规则是把SQL名称映射到操作系统区域的SQL模式对象。排序规则定义中有一个提供程序, 它指定哪个库提供语言环境数据。一个标准提供程序名称是`libc`, 它使用操作系统C库提供的语言环境。这些是操作系统提供的大多数工具使用的语言环境。 另一个提供程序是`icu`,它使用外部ICU库。 只有在构建MogDB时配置了对ICU的支持,才能使用ICU区域设置。 + +`libc`提供的一个排序规则对象映射到`LC_COLLATE` 和`LC_CTYPE`的组合, 如`setlocale()`系统库调用一样。 (顾名思义,排序规则的主要目的是设置`LC_COLLATE`, 它控制排序顺序。但在实际中很少需要一个和 `LC_COLLATE`不同的`LC_CTYPE`设置, 因此通过一个概念来收集这些信息比为了设置每一个表达式的 `LC_CTYPE`而创建另一种架构要更加方便)。此外,`libc`排序规则和字符集编码(见[字符集支持](./character-set-support.md)) 紧密关联。 对不同的编码可能存在同名的排序规则。 + +由`icu`提供的排序规则对象映射到由ICU库提供的指定整理器。 ICU不支持单独的“collate”和“ctype”设置, 所以它们总是相同的。此外,ICU排序规则与编码无关, 因此在数据库中总是只有一个给定名称的ICU排序规则。 + +### 标准的排序规则 + +在所有平台上,名称为`default`, `C`和`POSIX`排序规则都是可用的。其他可用的排序规则取决于操作系统支持。`default`排序规则选择在创建数据库时指定的`LC_COLLATE` 和`LC_CTYPE`值。 `C`和`POSIX`的排序规则都表现为"传统 C"的行为, 即只有ASCII字母"`A`"到"`Z`" 被视为字母,并且严格按照字符的编码字节值进行排序。 + +此外,SQL标准排序规则名称`ucs_basic`可用于编码`UTF8`。 它相当于`C`,并按Unicode代码点排序。 + +### 预定义的排序规则 + +如果操作系统提供了在一个程序中使用多语言环境的支持 (`newlocale`以及相关函数),那么当一个数据库集群初始化的时候, `gs_initdb`使用基于当时在操作系统上发现的所有语言环境的排序规则来填充系统表`pg_collation`。 + +要检查当前可用的语言环境,请在gsql中使用查询 `SELECT * FROM pg_collation`或命令`\dOS +`。 + +#### libc 排序规则 + +例如,操作系统可能提供名为`de_DE.utf8`的区域。 那么,`gs_initdb`就可能为编码`UTF8`创建命名为 `de_DE.utf8`的排序规则,它的`LC_COLLATE`和 `LC_CTYPE`都被设置为`de_DE.utf8`。 它还将创建名称中被剥离了`.utf8`标签的排序规则。 所以,也可以使用`de_DE`名称的排序规则 ,这方便于编写并且使得名称较少依赖于编码。然而,需要注意的是, 排序规则名称的初始设置是平台相关的。 + +由`libc`提供的默认排序规则直接映射到操作系统中安装的语言环境, 可以使用命令`locale -a`列出。 + +在任何特定的数据库中,只关心使用该数据库编码的排序规则。`pg_collation`中的其他项会被忽略。因此,剥离了编码名的排序规则名称,如`de_DE`,在一个给定的数据库中也算是独一无二的,即使它不是全局唯一的。 建议使用剥离过的排序规则名称,因为如果以后决定改变到另一个数据库编码,可以少改一样东西。 但是请注意,无论是什么数据库编码,都可以使用`default`, `C`和`POSIX`排序规则。 + +MogDB认为不同排序规则对象是不兼容的,即使他们有相同的属性。 例如: + +```sql +SELECT a COLLATE "C" < b COLLATE "POSIX" FROM test1; +``` + +将引起一个错误,即使`C`和`POSIX` 排序规则具有完全相同的行为。因此不推荐混合剥离的和非剥离的排序规则名。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/localization/locale-support.md b/product/zh/docs-mogdb/v3.1/administrator-guide/localization/locale-support.md new file mode 100644 index 00000000..0ece5275 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/localization/locale-support.md @@ -0,0 +1,68 @@ +--- +title: 区域支持 +summary: 区域支持 +author: Zhang Cuiping +date: 2022-07-26 +--- + +# 区域支持 + +区域支持指的是应用中考虑字母、排序、数值格式化等与文化相关的问题。MogDB使用服务器操作系统提供的标准ISO C 和POSIX区域机制。 + +## 概述 + +区域支持是在使用`gs_initdb`创建一个数据库集群时自动初始化的。默认情况下,`gs_initdb`将会按照它的执行环境的区域设置初始化数据库集群; 因此如果系统已经设置为数据库集群想要使用的区域, 那么无需进行任何操作。如果想使用其它的区域(或者不清楚系统当前设置的区域),可以用`--locale`选项告诉`gs_initdb`指定一个区域。 比如: + +``` +gs_initdb -D /opt/mogdb/data -w "XXXXXXXX" --nodename='data1' --locale=en_US +``` + +Unix系统下的这个例子就把区域设置为说瑞典语(`sv`),并且在瑞典地区(`SE`)。 其它的可能性是`en_US`(美国英语)和`fr_CA`(加拿大法语)等等。 如果有多于一种的字符集可以用于同一个区域,那么声明看起来会像`language_territory.codeset`。 比如,`fr_BE.UTF-8`表示为在比利时(BE)地区使用的法语(fr),并且使用UTF-8字符集编码。 + +系统上有哪些区域可用取决于操作系统提供商。在大部分Unix系统上,命令`locale -a`将会提供一个所有可用区域的列表。Windows会使用一些更繁琐的区域名,例如`German_Germany`或者`Swedish_Sweden.1252`,但是其原则是相同的。 + +有时,把几种区域规则混合起来也很有用,比如,使用英语排序规则而用西班牙语消息。 为了支持这些,我们有一套区域子类用于控制本地化规则的某些方面: + +| `LC_COLLATE` | 字符串排序顺序 | +| ------------- | --------------------------------------- | +| `LC_CTYPE` | 字符分类(什么是字符?是否区分大小写?) | +| `LC_MESSAGES` | 消息的语言 | +| `LC_MONETARY` | 货币金额的格式 | +| `LC_NUMERIC` | 数值格式 | +| `LC_TIME` | 日期和时间格式 | + +这些范畴名转换成`gs_initdb`选项的名字以覆盖某个特定范畴的区域选择。 比如,要把区域设置为加拿大法语,但使用美国的货币格式化规则, 可以使用`gs_initdb -D /opt/mogdb/data -w "XXXXXXXX" --nodename='data1' --locale=fr_CA --lc-monetary=en_US`。 + +如果想让系统表现得像没有区域支持一样,那么使用特殊的区域名`C`或者`POSIX`。 + +一些区域范畴的值必须在创建数据库时固定下来。 可以对不同的数据库使用不同的设置,但一旦创建一个数据库,就再也不能更改了。 `LC_COLLATE`和`LC_CTYPE`就是这样的范畴。 它们影响索引的排序顺序,因此它们必需保持固定,否则在文本字段上的索引将会崩溃。 (但是可以使用排序规则(collation)缓解这种限制, 参见[排序规则支持](./collation-support.md))。 当运行`gs_initdb`时确定这些范畴的缺省值, 这些值被用于创建新的数据库,除非在`CREATE DATABASE`命令中明确指定。 + +其它区域范畴可以在服务器启动的时候根据需要设置服务器配置参数来改变(详见[区域和格式化](../../reference-guide/guc-parameters/15-default-settings-of-client-connection/2-zone-and-formatting.md))。 `gs_initdb`选择的值实际上只是作为服务器启动时的缺省值写入 `postgresql.conf`配置文件。 如果在`postgresql.conf`里面删除了这些设置, 那么服务器将会继承来自运行环境的设置。 + +请注意服务器的区域行为是由它看到的环境变量决定的, 而不受客户端的环境影响。 因此,我们要在启动服务器之前认真地设置好这些变量。 这样带来的一种情况是如果客户端和服务器设置成不同的区域, 那么消息可能以不同的语言呈现,这取决于消息的来源。 + +> **注意**:从执行环境继承区域指在大多数操作系统上的下列动作: 对于一个给定的区域分类,比如排序规则,按照下面的顺序评估这些环境变量, 直到找到一个设置过的分类:`LC_ALL`、 `LC_COLLATE`(或者对应于相应分类的变量)、`LANG`。如果这些环境变量一个都没有被设置,那么将区域缺省设置为`C`。 +> +> 一些消息本地化库也可以查看环境变量`LANGUAGE`,它将覆盖所有其它用于设置消息语言的区域设置。如果有疑问, 请参考相关操作系统文档,特别是有关gettext的文档。 + +## 行为 + +区域设置影响下面的 SQL 特性: + +- 查询中使用`ORDER BY`或者对文本数据的标准比较操作符进行排序 +- `upper`, `lower`和`initcap`函数 +- 模式匹配运算符(`LIKE`, `SIMILAR TO`, 以及POSIX-风格的正则表达式); 区域影响大小写不敏感的匹配和通过字符分类正则表达式的字符分类。 +- `to_char`函数族 +- 使用`LIKE`子句的索引能力 + +MogDB中使用非`C`或非`POSIX`区域的缺点是性能影响。它降低了字符处理的速度并且阻止了在`LIKE`类查询中对普通索引的使用。因此,只能在真正需要的时候才使用它。 + +为了允许MogDB在非C区域下的`LIKE`子句中使用索引, 有好几个自定义的操作符类可以用。 这些操作符类允许创建一个严格地比较每个字符的索引, 而忽略区域比较规则。另外一个方法是使用`C` collation创建索引,参见[排序规则支持](./collation-support.md)。 + +## 问题 + +如果根据以上区域支持仍然不能运行,检查操作系统的区域支持是否被正确配置。可以使用`locale -a`命令(如果系统提供了该命令)。 + +请检查MogDB正在使用正确的区域设置。`LC_COLLATE`和`LC_CTYPE`设置都是在数据库创建时设置的,并且在除了创建数据库之外的操作中都不能被更改。其它的区域设置包括`LC_MESSAGES`和`LC_MONETARY`都是由服务器启动的环境决定的, 但是可以在运行时修改。可以用`SHOW`命令检查活跃的区域设置。 + +那些通过分析错误消息来处理服务器端错误的客户端应用很明显会有问题,因为服务器来的消息可能会以不同语言表示。 我们建议这类应用的开发人员改用错误代码机制。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/1-mot-introduction.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/1-mot-introduction.md new file mode 100644 index 00000000..3cdac244 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/1-mot-introduction.md @@ -0,0 +1,29 @@ +--- +title: MOT简介 +summary: MOT简介 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT简介 + +MogDB引入了MOT存储引擎,它是一种事务性行存储,针对多核和大内存服务器进行了优化。MOT是MogDB数据库最先进的生产级特性(Beta版本),它为事务性工作负载提供更高的性能。MOT完全支持ACID特性,并包括严格的持久性和高可用性支持。企业可以在关键任务、性能敏感的在线事务处理(OLTP)中使用MOT,以实现高性能、高吞吐、可预测低延迟以及多核服务器的高利用率。MOT尤其适合在多路和多核处理器的现代服务器上运行,例如基于Arm/鲲鹏处理器的华为TaiShan服务器,以及基于x86的戴尔或类似服务器。 + +**图 1** MogDB内存优化存储引擎 + +![mogdb内存优化存储引擎](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-introduction-1.png) + +如[图1](#neicun)所示,MogDB数据库内存优化存储引擎组件(绿色部分)负责管理MOT和事务。 + +MOT与基于磁盘的普通表并排创建。MOT的有效设计实现了几乎完全的SQL覆盖,并且支持完整的数据库功能集,如存储过程和自定义函数(限制参见[MOT SQL覆盖和限制](../../../administrator-guide/mot-engine/2-using-mot/4-mot-usage.md#mot-sql覆盖和限制))。 + +通过完全存储在内存中的数据和索引、非统一内存访问感知(NUMA-aware)设计、消除锁和锁存争用的算法以及查询原生编译,MOT可提供更快的数据访问和更高效的事务执行。 + +MOT有效的几乎无锁的设计和高度调优的实现,使其在多核服务器上实现了卓越的近线性吞吐量扩展,这可能是业界最好的。 + +MOT完全支持ACID特性: + +- 原子性(Atomicity):原子事务是一系列不可分割的数据库操作。在事务完成(分别提交或中止)之后,这些操作要么全部发生,要么全部不发生。 +- 一致性(Consistency):事务结束后,数据库处于一致状态,保留数据完整性。 +- 隔离性(Isolation):事务之间不能相互干扰。MOT支持不同的重复读和读提交隔离级别。在下一个版本中,MOT还将支持可序列化隔离。更多信息,请参见[MOT隔离级别](../../../administrator-guide/mot-engine/3-concepts-of-mot/3-2.md#mot隔离级别)。 +- 持久性(Durability):即使发生崩溃和失败,成功完成(提交)的事务效果持久保存。MOT完全集成了MogDB的基于WAL的日志记录。同时支持同步和异步日志记录选项。MOT还支持同步+面向NUMA优化的组提交。更多信息,请参见[MOT持久性概念](../../../administrator-guide/mot-engine/3-concepts-of-mot/3-6.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/2-mot-features-and-benefits.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/2-mot-features-and-benefits.md new file mode 100644 index 00000000..f46cfdd2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/2-mot-features-and-benefits.md @@ -0,0 +1,22 @@ +--- +title: MOT特性及价值 +summary: MOT特性及价值 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT特性及价值 + +MOT在高性能(查询和事务延迟)、高可扩展性(吞吐量和并发量)以及高资源利用率(某些程度上节约成本)方面拥有显著优势。 + +- 低延迟(Low Latency):提供快速的查询和事务响应时间。 +- 高吞吐量(High Throughput):支持峰值和持续高用户并发。 +- 高资源利用率(High Resource Utilization):充分利用硬件。 + +使用了MOT的应用程序可以达到普通表2.5到4倍的吞吐量。例如,在基于Arm/鲲鹏的华为TaiShan服务器和基于英特尔至强的戴尔x86服务器上,执行TPC-C基准测试(交互事务和同步日志),MOT提供的吞吐率增益在2路服务器上达到2.5倍,4路服务器上达到3.7倍,在4路256核Arm服务器上达到480万tpmC。 + +在TPC-C基准测试中可观察到,MOT提供更低的延迟,将事务处理速度提升了3至5.5倍。 + +此外,高负载和高争用的场景是所有领先的行业数据库都会遇到的公认问题,而MOT能够在这种情况下极高地利用服务器资源。使用MOT后,4路服务器的资源利用率达到99%,远远领先其他行业数据库。 + +这种能力在现代的多核服务器上尤为明显和重要。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/3-mot-key-technologies.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/3-mot-key-technologies.md new file mode 100644 index 00000000..471403a5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/3-mot-key-technologies.md @@ -0,0 +1,24 @@ +--- +title: MOT关键技术 +summary: MOT关键技术 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT关键技术 + +MOT的关键技术如下: + +- 内存优化数据结构:以实现高并发吞吐量和可预测的低延迟为目标,所有数据和索引都在内存中,不使用中间页缓冲区,并使用持续时间最短的锁。数据结构和所有算法都是专门为内存设计而优化的。 +- 免锁事务管理:MOT在保证严格一致性和数据完整性的前提下,采用乐观的策略实现高并发和高吞吐。在事务过程中,MOT不会对正在更新的数据行的任何版本加锁,从而大大降低了一些大内存系统中的争用。事务中的乐观并发控制(Optimistic Concurrency Control,OCC)语句是在没有锁的情况下实现的,所有的数据修改都是在内存中专门用于私有事务的部分(也称为私有事务内存)中进行的。这就意味着在事务过程中,相关数据在私有事务内存中更新,从而实现了无锁读写;而且只有在提交阶段才会短时间加锁。更多详细信息,请参见[MOT并发控制机制](../../../administrator-guide/mot-engine/3-concepts-of-mot/3-2.md)。 +- 免锁索引:由于内存表的数据和索引完全存储在内存中,因此拥有一个高效的索引数据结构和算法非常重要。MOT索引机制基于最先进的Masstree,这是一种用于多核系统的快速和可扩展的键值(Key Value,KV)存储索引,以B+树的Trie实现。通过这种方式,高并发工作负载在多核服务器上可以获得卓越的性能。同时MOT应用了各种先进的技术以优化性能,如优化锁方法、高速缓存感知和内存预取。 +- NUMA-aware的内存管理:MOT内存访问的设计支持非统一内存访问(NUMA)感知。NUMA-aware算法增强了内存中数据布局的性能,使线程访问物理上连接到线程运行的核心的内存。这是由内存控制器处理的,不需要通过使用互连(如英特尔QPI)进行额外的跳转。MOT的智能内存控制模块,为各种内存对象预先分配了内存池,提高了性能,减少了锁,保证了稳定性。事务的内存对象的分配始终是NUMA本地的。本地处理的对象会返回到池中。同时在事务中尽量减少系统内存分配(OS malloc)的使用,避免不必要的锁。 +- 高效持久性:日志和检查点是实现磁盘持久化的关键能力,也是ACID的关键要求之一(D代表持久性)。目前所有的磁盘(包括SSD和NVMe)都明显慢于内存,因此持久化是基于内存数据库引擎的瓶颈。作为一个基于内存的存储引擎,MOT的持久化设计必须实现各种各样的算法优化,以确保持久化的同时还能达到设计时的速度和吞吐量目标。这些优化包括: + - 并行日志,所有MogDB磁盘表都支持。 + - 每个事务的日志缓冲和无锁事务准备。 + - 增量更新记录,即只记录变化。 + - 除了同步和异步之外,创新的NUMA感知组提交日志记录。 + - 最先进的数据库检查点(CALC)使内存和计算开销降到最低。 +- 高SQL覆盖率和功能集:MOT通过扩展的PostgreSQL外部数据封装(FDW)以及索引,几乎支持完整的SQL范围,包括存储过程、用户定义函数和系统函数调用。有关不支持的功能的列表,请参阅[MOT SQL覆盖和限制](../../../administrator-guide/mot-engine/2-using-mot/4-mot-usage.md#mot-sql覆盖和限制)。 +- 使用PREPARE语句的查询原生编译:通过使用PREPARE客户端命令,可以以交互方式执行查询和事务语句。这些命令已被预编译成原生执行格式,也称为Code-Gen或即时(Just-in-Time,JIT)编译。这样可以实现平均30%的性能提升。在可能的情况下,应用编译和轻量级执行;否则,使用标准执行路径处理适用的查询。Cache Plan模块已针对OLTP进行了优化,在整个会话中甚至使用不同的绑定设置以及在不同的会话中重用编译结果。 +- MOT和MogDB数据库的无缝集成:MOT是一个高性能的面向内存优化的存储引擎,已集成在MogDB包中。MOT的主内存引擎和基于磁盘的存储引擎并存,以支持多种应用场景,同时在内部重用数据库辅助服务,如WAL重做日志、复制、检查点和恢复高可用性等。用户可以从基于磁盘的表和MOT的统一部署、配置和访问中受益。根据特定需求,灵活且低成本地选择使用哪种存储引擎。例如,把会导致瓶颈的高度性能敏感数据放入内存中。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/4-mot-usage-scenarios.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/4-mot-usage-scenarios.md new file mode 100644 index 00000000..2e890b32 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/4-mot-usage-scenarios.md @@ -0,0 +1,22 @@ +--- +title: MOT应用场景 +summary: MOT应用场景 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT应用场景 + +MOT可以根据负载的特点,显著加快应用程序的整体性能。MOT通过提高数据访问和事务执行的效率,并通过消除并发执行事务之间的锁和锁存争用,最大程度地减少重定向,从而提高了事务处理的性能。 + +MOT的极速不仅因为它在内存中,还因为它围绕并发内存使用管理进行了优化。数据存储、访问和处理算法从头开始设计,以利用内存和高并发计算的最新先进技术。 + +MogDB允许应用程序随意组合MOT和基于标准磁盘的表。对于启用已证明是瓶颈的最活跃、高争用和对性能敏感的应用程序表,以及需要可预测的低延迟访问和高吞吐量的表来说,MOT特别有用。 + +MOT可用于各种应用,例如: + +- 高吞吐事务处理:这是使用MOT的主要场景,因为它支持海量事务,同时要求单个事务的延迟较低。这类应用的例子有实时决策系统、支付系统、金融工具交易、体育博彩、移动游戏、广告投放等。 +- 性能瓶颈加速:存在高争用现象的表可以通过使用MOT受益,即使该表是磁盘表。由于延迟更低、竞争和锁更少以及服务器吞吐量能力增加,此类表(除了相关表和在查询和事务中一起引用的表之外)的转换使得性能显著提升。 +- 消除中间层缓存:云计算和移动应用往往会有周期性或峰值的高工作负载。此外,许多应用都有80%以上负载是读负载,并伴有频繁的重复查询。为了满足峰值负载单独要求,以及降低响应延迟提供最佳的用户体验,应用程序通常会部署中间缓存层。这样的附加层增加了开发的复杂性和时间,也增加了运营成本。 MOT提供了一个很好的替代方案,通过一致的高性能数据存储来简化应用架构,缩短开发周期,降低CAPEX和OPEX成本。 +- 大规模流数据提取:MOT可以满足云端(针对移动、M2M和物联网)、事务处理(Transactional Processing,TP)、分析处理(Analytical Processing,AP)和机器学习(Machine Learning,ML)的大规模流数据的提取要求。MOT尤其擅长持续快速地同时提取来自许多不同来源的大量数据。这些数据可以在以后进行处理、转换,并在速度较慢的基于磁盘的表中进行移动。另外,MOT还可以查询到一致的、最新的数据,从而得出实时结果。在有许多实时数据流的物联网和云计算应用中,通常会有专门的数据摄取和处理。例如,一个Apache Kafka集群可以用来提取10万个事件/秒的数据,延迟为10ms。一个周期性的批处理任务会将收集到的数据收集起来,并将转换格式,放入关系型数据库中进行进一步分析。MOT可以通过将数据流直接存储在MOT关系表中,为分析和决策做好准备,从而支持这样的场景(同时消除单独的数据处理层)。这样可以更快地收集和处理数据,MOT避免了代价高昂的分层和缓慢的批处理,提高了一致性,增加了分析数据的实时性,同时降低了总拥有成本(Total Cost of Ownership,TCO)。 +- 降低TCO:提高资源利用率和消除中间层可以节省30%到90%的TCO。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/5-mot-performance-benchmarks.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/5-mot-performance-benchmarks.md new file mode 100644 index 00000000..45413d3f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/1-introducing-mot/5-mot-performance-benchmarks.md @@ -0,0 +1,204 @@ +--- +title: MOT性能基准 +summary: MOT性能基准 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT性能基准 + +我们的性能测试是基于业界和学术界通用的TPC-C基准。 + +测试使用了BenchmarkSQL(请参见[MOT样例TPC-C基准](../../../administrator-guide/mot-engine/2-using-mot/6-mot-sample-tpcc-benchmark.md)),并且使用交互式SQL命令而不是存储过程来生成工作负载。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 使用存储过程方法可能会产生更高的性能结果,因为它需要大大减少网络往返和数据库封装SQL处理周期。 + +评估MogDB MOT性能和磁盘性能的所有测试都使用了同步日志记录和在MOT中优化的group-commit=on版本。 + +最后我们进行了额外测试,评估MOT快速采集大量数据的能力,并将其作为中间层数据采集解决方案的替代方案。 + +2020年6月完成全部测试。 + +下面是各种类型的MOT性能基准。 + +
+ +## MOT硬件 + +本次测试使用的服务器满足10GbE组网和以下配置: + +- 基于Arm64/鲲鹏920的2路服务器,型号为TaiShan 2280 v2(128核),800GB RAM,1TB NVMe盘。服务器详细规格参见[此页面](https://e.huawei.com/cn/products/servers/taishan-server/taishan-2480-v2)。操作系统为openEuler。 +- 基于Arm64/鲲鹏960的4路服务器,型号为TaiShan 2480 v2(256核),512GB RAM,1TB NVMe盘。服务器详细规格参见[此页面](https://e.huawei.com/cn/products/servers/taishan-server/taishan-2480-v2)。操作系统为openEuler。 +- 戴尔x86服务器,2路英特尔至强金牌6154 CPU @ 3Ghz,18核(超线程开启时共72核),1TB RAM,1TB SSD。操作系统为CentOS 7.6。 +- x86超微服务器,8路英特尔(R)至强(R) CPU E7-8890 v4 @ 2.20GHz,24核(超线程开启共384核),1TB RAM,1.2 TB SSD(希捷1200 SSD 200GB,SAS 12Gb/s)。操作系统为Ubuntu 16.04.2 LTS。 +- 华为x86服务器,4路英特尔(R)至强(R) CPU E7-8890 v4 @ 2.2Ghz(超线程开启共96核),512GB RAM,SSD 2TB。操作系统为CentOS 7.6。 + +
+ +## MOT测试总结 + +MOT比磁盘表性能提升2.5至4.1倍,在Arm/鲲鹏256核服务器上达到480万tpmC。测试结果清楚表明MOT在扩展和利用所有硬件资源方面的卓越能力。随着CPU槽位和服务器核数增加,性能会随之跃升。 + +MOT在Arm/鲲鹏架构下最高可达3万tpmC/核,在x86架构下最高可达4万tpmC/核。 + +由于持久性机制更高效,MOT中的复制开销在Arm/鲲鹏主备高可用场景下为7%,在x86服务器中为2%。而磁盘表的开销在Arm/鲲鹏中为20%,在x86中为15%。 + +最终,MOT延迟降低2.5倍,TPC-C事务响应速度提升2至7倍。 + +
+ +## MOT高吞吐量 + +MOT高吞吐量测试结果如下。 + +
+ +### Arm/鲲鹏2路128核 + +- **性能** + + 下图是华为Arm/鲲鹏2路128核服务器TPC-C基准测试的结果。 + + 一共进行了四类测试: + + - MOT和MogDB基于磁盘的表各进行了2次测试。 + - 其中两项测试是在单节点(无高可用性)上执行,这意味着没有向备节点执行复制。其余两个测试在主备节点(有高可用性)上执行,即写入主节点的数据被复制到备节点。 + + MOT用橙色表示,基于磁盘的表用蓝色表示。 + + **图 1** Arm/鲲鹏2路128核性能基准 + + ![Arm-鲲鹏2路128核性能基准](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-1.png) + + 结果表明: + + - 正如预期的那样,在所有情况下,MOT的性能明显高于基于磁盘的表。 + - 单节点:MOT性能为380万tpmC,而基于磁盘的表为150万tpmC。 + - 主备节点:MOT性能为350万tpmC,而基于磁盘的表为120万tpmC。 + - 相比单节点(无高可用性,无复制),在有复制需求的生产级(高可用性)服务器(主备节点)上,使用MOT的好处更显著。 + - 同在主备高可用场景下,MOT复制开销:Arm/鲲鹏为7%,x86为2%;而基于磁盘的表复制开销:Arm/鲲鹏为20%;x86为15%。 + +- **单CPU核性能** + + 下图是华为Arm/鲲鹏服务器2路128核的单核TPC-C基准性能/吞吐量测试结果。同样地,一共进行了四类测试: + + **图 2** Arm/鲲鹏2路128核的单核性能标杆 + + ![Arm-鲲鹏2路128核的单核性能标杆](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-2.png) + + 结果表明,正如预期的那样,在所有情况下,MOT的单核性能明显高于基于磁盘的表。相比单节点(无高可用性,无复制),在有复制需求的生产级(高可用性)服务器(主备节点)上,使用MOT的好处更显著。 + +
+ +### Arm/鲲鹏4路256核 + +下面通过单连接数的tpmC来展示MOT出色的并发控制性能。 + +**图 3** Arm/鲲鹏4路256核性能基准 + +![Arm-鲲鹏4路256核性能基准](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-3.png) + +结果表明,随着核数增多,性能也显著提高,在768核时性能达到480万tpmC的峰值。 + +
+ +### x86服务器 + +- **8路384核** + +下面通过比较基于磁盘的表和MOT之间单连接数的tpmC,来展示MOT出色的并发控制性能。本次测试以8路384核x86服务器为例。橙色表示MOT的结果。 + +**图 4** 8路384核x86服务器性能基准 + +![8路384核x86服务器性能基准](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-4.png) + +结果表明,在386核服务器上,MOT的性能明显优于基于磁盘的表,并且单核性能非常高,达到300万tpmC/核。 + +- **4路96核** + +在4路96核服务器上,MOT实现了390万tpmC。下图展示了高效MOT的单核性能达到4万tpmC/核。 + +**图 5** 4路96核服务器性能基准 + +![4路96核服务器性能基准](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-5.png) + +
+ +## MOT低延迟 + +以下是在Arm/鲲鹏两路服务器(128核)上进行测试的结果。单位为毫秒(ms)。 + +**图 1** 低延迟(90th%)性能基准 + +![低延迟(90th-)性能基准](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-6.png) + +MOT的平均事务速度为2.5倍,MOT延迟为10.5ms,而基于磁盘的表延迟为23至25ms。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 计算平均数时,已考虑TPC-C的5个事务分布占比。有关更多信息,请参阅[MOT样例TPC-C基准](../../../administrator-guide/mot-engine/2-using-mot/6-mot-sample-tpcc-benchmark.md)中关于TPC-C事务的说明。 + +**图 2** 低延迟(90th%,事务平均)性能基准 + +![低延迟(90th-事务平均)性能基准](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-7.png) + +
+ +## MOT恢复时间目标(RTO)和冷启动时间 + +### 高可用RTO + +MOT完全集成到MogDB中,包括支持主备部署的高可用场景。WAL重做日志的复制机制将把复制更改到数据库备节点并使用备节点进行重放。 + +如果故障转移事件发生,无论是由于计划外的主节点故障还是由于计划内的维护事件,备节点都会迅速活跃。恢复和重放WAL重做日志以及启用连接所需的时间也称为恢复时间目标(RTO)。 + +**MogDB(包括MOT)的RTO小于10秒。** + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 灾难发生后必须恢复业务流程,避免导致连续性中断相关的不可接受的后果,而RTO表示的就是这段流程的持续时间和业务级别。换句话说,RTO就是在回答这个问题:在通知业务流程中断后,需要多长时间才能恢复? + +另外,从[MOT高吞吐量](#mot高吞吐量)的MOT中可以看出,在Arm/鲲鹏架构下,主从高可用场景复制开销仅为7%,在x86架构下仅为2%,而基于磁盘的表复制开销为2%。Arm/鲲鹏机型为20%,x86机型为15%。 + +
+ +### 冷启动恢复时间 + +冷启动恢复时间是指系统从停止模式到能够完全运行所需的时间。在内存数据库中,这包括将所有数据和索引加载到内存中的时间,因此它取决于数据大小、硬件带宽和软件算法能否高效地处理这些数据。 + +MOT测试使用40 GB/s的ARM磁盘测试,可以在100 GB/s的时间内加载数据库。MOT的索引非持久化,因此它们是在冷启动时创建的。实际加载的数据加索引大小约多50%。因此,可以转换为MOT冷启动时间的数据和索引容量为40秒内150GB,或225 GB/分钟(3.75 GB/秒)。 + +冷启动过程和从磁盘加载数据到MOT所需时间如下图所示。 + +**图 1** 冷启动时间性能基准 + +![冷启动时间性能基准](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-8.png) + +- 数据库大小:加载整个数据库(每数据库GB)的总时间由蓝色线条和左侧的Y轴“时间(秒)”表示。 +- 吞吐量:数据库每秒GB吞吐量由橙色线和右侧的Y轴“吞吐量GB/秒”表示。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 测试过程中表现的性能与SSD硬件的带宽非常接近。因此,可以在不同的平台上实现更高(或更低)的性能。 + +
+ +## MOT资源利用率 + +在4路96核512GB RAM的x86服务器上测试的资源利用率如下所示。MOT能够高效持续消耗几乎所有可用的CPU资源。例如,192核390万tpmC的CPU利用率几乎达到100%。 + +- tmpC:每分钟完成的TPC-C事务数以橙色条柱和左侧的Y轴“tpmC”表示。 +- CPU利用率(%):CPU利用率由蓝色线条和右侧的Y轴“CPU%”表示。 + +**图 1** 资源利用率性能基准 + +![资源利用率性能基准](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-9.png) + +
+ +## MOT数据采集速度 + +该测试模拟海量物联网、云端或移动端接入的实时数据流,快速持续地把海量数据注入到数据库。 + +- 本次测试涉及大量数据采集,具体如下: + - 1000万行数据由500个线程发送,2000轮,每个insert命令有10条记录(行),每条记录占200字节。 + - 客户端和数据库位于不同的机器上。 数据库服务器为2路72核x86服务器。 +- 性能结果 + - 吞吐量:10000个记录/核,或2MB/核。 + - 延迟:2.8ms每10条记录批量插入(包括客户端-服务器组网)。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** 预计MOT将针对这一场景进行多项额外的甚至重大的性能改进。更多关于大规模数据流和数据采集的信息,请参阅[MOT应用场景](4-mot-usage-scenarios.md)。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/1-using-mot-overview.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/1-using-mot-overview.md new file mode 100644 index 00000000..fdfdef50 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/1-using-mot-overview.md @@ -0,0 +1,18 @@ +--- +title: MOT使用概述 +summary: MOT使用概述 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT使用概述 + +MOT作为MogDB的一部分自动部署。有关如何计算和规划所需的内存和存储资源以维持工作负载的说明,请参阅[MOT准备](2-mot-preparation.md)。参考[MOT部署](3-mot-deployment.md)了解MOT中所有的配置,以及服务器优化的非必须选项。 + +使用MOT的方法非常简单。MOT命令的语法与基于磁盘的表的语法相同,并支持大多数标准,如PostgreSQL SQL、DDL和DML命令和功能,如存储过程。只有MOT中的创建和删除表语句与MogDB中基于磁盘的表的语句不同。您可以参考[MOT使用](4-mot-usage.md)了解这两个简单命令的说明,如何将基于磁盘的表转换为MOT,如何使用查询原生编译和PREPARE语句获得更高的性能,以及了解外部工具支持和MOT引擎的限制。 + +[MOT管理](5-mot-administration.md)介绍了如何进行数据库维护,以及监控和分析日志和错误报告。最后,[MOT样例TPC-C基准](6-mot-sample-tpcc-benchmark.md)介绍了如何执行标准TPC-C基准测试。 + +- 阅读以下内容了解如何使用MOT: + + ![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/using-mot-overview-1.png) diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/2-mot-preparation.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/2-mot-preparation.md new file mode 100644 index 00000000..30eb93b6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/2-mot-preparation.md @@ -0,0 +1,226 @@ +--- +title: MOT准备 +summary: MOT准备 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT准备 + +下文介绍了使用MOT的前提条件以及内存和存储规划。 + +
+ +## 前提条件 + +以下是使用MogDB MOT的软硬件前提条件。 + +
+ +### 硬件支持 + +MOT支持最新硬件和现有硬件平台,支持x86架构和华为鲲鹏Arm架构。 + +MOT与MogDB数据库支持的硬件完全对齐。 + +
+ +### CPU + +MOT在多核服务器(扩容)上提供卓越的性能。在这些环境中,MOT的性能明显优于友商,并提供近线性扩展和极高的资源利用率。 + +用户也可以开始在低端、中端和高端服务器上实现MOT的性能优势,无论CPU槽位是1或2个,还是4个,甚至是8个也没问题。在16路甚至32路的高端服务器上,性能和资源利用率也非常高(建议与云和恩墨技术支持联系)。 + +
+ +### 内存 + +MOT支持标准RAM/DRAM用于其数据和事务管理。所有MOT数据和索引都驻留在内存中,因此内存容量必须能够支撑数据容量,并且还有进一步增长的空间。内存需求和规划请参见[MOT内存和存储规划](#mot内存和存储规划)。 + +
+ +### 存储IO + +MOT是一个持久的数据库,使用永久性存储设备(磁盘/SSD/NVMe驱动器)进行事务日志操作和存储定期检查点。 + +推荐采用低延迟的存储设备,如配置RAID-1的SSD、NVMe或者任何企业级存储系统。当使用适当的硬件时,数据库事务处理和竞争将成为瓶颈,而非IO。 + +详细的内存要求和规划请参见[MOT内存和存储规划](#mot内存和存储规划)。 + +操作系统支持 + +MOT与MogDB支持的操作系统完全对齐。 + +MOT支持裸机和虚拟化环境,可以在裸机或虚拟机上运行以下操作系统: + +- x86:CentOS 7.6和EulerOS 2.0 +- Arm:openEuler和EulerOS + +
+ +### 操作系统优化 + +MOT不需要任何特殊修改或安装新软件。但是,一些优化可以提高性能。有关实现最大性能的优化说明,请参阅[MOT服务器优化:x86](3-mot-deployment.md#mot服务器优化x86)和[MOT服务器优化:基于Arm的华为TaiShan2P/4P服务器](3-mot-deployment.md#mot服务器优化基于arm的华为taishan2p4p服务器)。 + +
+ +## MOT内存和存储规划 + +本节描述了为满足特定应用程序需求,在评估、估计和规划内存和存储容量数量时,需要注意的事项和准则,以及影响所需内存数量的各种数据,例如计划表的数据和索引大小、维持事务管理的内存以及数据增长的速度。 + +
+ +### MOT内存规划 + +MOT是一种内存数据库存储引擎(IMDB),其中所有表和索引完全驻留在内存中。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 内存存储是易失的,需要电力来维护所存储的信息。磁盘存储是持久的,写入磁盘是非易失性存储。MOT使用两种存储,既把所有数据保存在内存中,也把事务性更改同步(通过WAL日志记录)到磁盘上以保持严格一致性(使用同步日志记录模式)。 + +服务器上必须有足够的物理内存以维持内存表的状态,并满足工作负载和数据的增长。所有这些都是在传统的基于磁盘的引擎、表和会话所需的内存之外的要求。因此,提前规划好足够的内存来容纳这些内容是非常有必要的。 + +开始可以使用任何数量的内存并执行基本任务和评估测试。但当准备好生产时,应解决以下问题: + +- **内存配置** + + MogDB数据库和标准Postgres类似,其内存上限是由max_process_memory设置的,该上限在postgres.conf文件中定义。MOT及其所有组件和线程,都驻留在MogDB进程中。因此,分配给MOT的内存也是在整个MogDB数据库进程的max_process_memory定义的上限内分配。 + + MOT为自己保留的内存是max_process_memory的一部分。可以通过百分比或通过小于max_process_memory的绝对值定义。这个部分在mot.conf配置文件中由_mot__memory配置项定义。 + + max_process_memory中可以除了被MOT使用的部分之外,必须为Postgres(MogDB)封装留下至少2GB的可用空间。为了确保这一点,MOT在数据库启动过程中会进行如下校验: + + ``` + (max_mot_global_memory + max_mot_local_memory) + 2GB < max_process_memory + ``` + + 如果违反此限制,则调整MOT内存内部限制,最大可能地满足上述限制范围。该调整在启动时进行,并据此计算MOT最大内存值。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: MOT最大内存值是配置或调整值(max_mot_global_memory + max_mot_local_memory)的逻辑计算值。 + + 此时,会向服务器日志发出警告,如下所示: + + 以下是报告问题的警告消息示例: + + ``` + [WARNING] MOT engine maximum memory definitions (global: 9830 MB, local: 1843 MB, session large store: 0 MB, total: 11673 MB) breach GaussDB maximum process memory restriction (12288 MB) and/or total system memory (64243 MB). MOT values shall be adjusted accordingly to preserve required gap (2048 MB). + ``` + + 以下警告消息示例提示MOT正在自动调整内存限制: + + ``` + [WARNING] Adjusting MOT memory limits: global = 8623 MB, local = 1617 MB, session large store = 0 MB, total = 10240 MB + ``` + + 新内存限制仅在此处显示。 + + 此外,当总内存使用量接近所选内存限制时,MOT不再允许插入额外数据。不再允许额外数据插入的阈值即是MOT最大内存百分比(如上所述,这是一个计算值)。MOT最大内存百分比默认值为90,即90%。尝试添加超过此阈值的额外数据时,会向用户返回错误,并且也会注册到数据库日志文件中。 + +- **最小值和最大值** + + 为了确保内存安全,MOT根据最小的全局和本地设置预先分配内存。数据库管理员应指定MOT和会话维持工作负载所需的最小内存量。这样可以确保即使另一个消耗内存的应用程序与数据库在同一台服务器上运行,并且与数据库竞争内存资源,也能够将这个最小的内存分配给MOT。最大值用于限制内存增长。 + +- **全局和本地** + + MOT使用的内存由两部分组成: + + - 全局内存:全局内存是一个长期内存池,包含MOT的数据和索引。它平均分布在NUMA节点,由所有CPU核共享。 + + - 本地内存:本地内存是用于短期对象的内存池。它的主要使用者是处理事务的会话。这些会话将数据更改存储在专门用于相关特定事务的内存部分(称为事务专用内存)。在提交阶段,数据更改将被移动到全局内存中。内存对象分配以NUMA-local方式执行,以实现尽可能低的延迟。 + + 被释放的对象被放回相关的内存池中。在事务期间尽量少使用操作系统内存分配(malloc)函数,避免不必要的锁和锁存。 + + 这两个内存的分配由专用的min/max_mot_global_memory和min/max_mot_local_memory设置控制。如果MOT全局内存使用量太接近最大值,则MOT会保护自身,不接受新数据。超出此限制的内存分配尝试将被拒绝,并向用户报告错误。 + +- **最低内存要求** + + 在开始执行对MOT性能的最小评估前,请确保: + + 除了磁盘表缓冲区和额外的内存,max_process_memory(在postgres.conf中定义)还有足够的容量用于MOT和会话(由mix/max_mot_global_memory和mix/max_mot_local_memory配置)。对于简单的测试,可以使用mot.conf的默认设置。 + +- **生产过程中实际内存需求** + + 在典型的OLTP工作负载中,平均读写比例为80:20,每个表的MOT内存使用率比基于磁盘的表高60%(包括数据和索引)。这是因为使用了更优化的数据结构和算法,使得访问速度更快,并具有CPU缓存感知和内存预取功能。 + + 特定应用程序的实际内存需求取决于数据量、预期工作负载,特别是数据增长。 + +- **最大全局内存规划:数据和索引大小** + + 要规划最大全局内存,需满足: + + 1. 确定特定磁盘表(包括其数据和所有索引)的大小。如下统计查询可以确定customer表的数据大小和customer_pkey索引大小: + + - 数据大小:选择pg_relation_size('customer'); + - 索引:选择pg_relation_size('customer_pkey'); + + 2. 额外增加60%的内存,相对于基于磁盘的数据和索引的当前大小,这是MOT中的常见要求。 + + 3. 额外增加数据预期增长百分比。例如: + + 5%月增长率 = 80%年增长率(1.05^12)。因此,为了维持年增长,需分配比表当前使用的还多80%的内存。 + + 至此,max_mot_global_memory值的估计和规划就完成了。实际设置可以用绝对值或Postgres max_process_memory的百分比来定义。具体的值通常在部署期间进行微调。 + +- **最大本地内存规划:并发会话支持** + + 本地内存需求主要是并发会话数量的函数。平均会话的典型OLTP工作负载最大占用8MB。此值乘以会话的数量,再加一点额外的值。 + + 可以通过这种方式进行内存计算,然后进行微调: + + ```bash + SESSION_COUNT * SESSION_SIZE (8 MB) + SOME_EXTRA (100MB should be enough) + ``` + + 默认指定Postgres最大进程内存(默认为12GB)的15%。相当于1.8GB可满足230个会话,即max_mot_local内存需求。实际设置可以用绝对值或Postgres max_process_memory的百分比来定义。具体的值通常在部署期间进行微调。 + +- **异常大事务** + + 某些事务非常大,因为它们将更改应用于大量行。这可能导致单个会话的本地内存增加到允许的最大限制,即1GB。例如: + + ```sql + delete from SOME_VERY_LARGE_TABLE; + ``` + + 在配置max_mot_local_memory设置和应用程序开发时,请考虑此场景。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 有关配置的更多信息,请参阅[内存(MOT)](3-mot-deployment.md#内存mot)部分。 + +
+ +### 存储IO + +MOT是一个内存优化的持久化数据库存储引擎。需要磁盘驱动器来存储WAL重做日志和定期检查点。 + +推荐采用低延迟的存储设备,如配置RAID-1的SSD、NVMe或者任何企业级存储系统。当使用适当的硬件时,数据库事务处理和竞争将成为瓶颈,而非IO。 + +由于持久性存储比RAM内存慢得多,因此IO操作(日志和检查点)可能成为内存中数据库和内存优化数据库的瓶颈。但是,MOT具有针对现代硬件(如SSD、NVMe)进行优化的高效持久性设计和实现。此外,MOT最小化和优化了写入点(例如,使用并行日志记录、每个事务的单日志记录和NUMA-aware事务组写入),并且最小化了写入磁盘的数据(例如,只把更改记录的增量或更新列记录到日志,并且只记录提交阶段的事务)。 + +
+ +### 容量需求 + +所需容量取决于检查点和记录的要求,如下所述: + +- **检查点** + + 检查点将所有数据的快照保存到磁盘。 + + 需要给检查点分配两倍数据大小的容量。不需要为检查点索引分配空间。 + + 检查点 = 2 x MOT数据大小(仅表示行,索引非持久)。 + + 检查点之所以需要两倍大小,是因为快照会保存数据的全部大小到磁盘上,此外还应该为正在进行的检查点分配同样数量的空间。当检查点进程结束时,以前的检查点文件将被删除。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 在下一个MogDB版本中,MOT将有一个增量检查点特性,这将大大降低存储容量需求。 + +- **日志记录** + + MOT日志记录与基于磁盘的表的其它记录写入同一个数据库事务日志。 + + 日志的大小取决于事务吞吐量、数据更改的大小和检查点之间的时间(每次检查点,重做日志被截断并重新开始扩展)。 + + 与基于磁盘的表相比,MOT使用较少的日志带宽和较低的IO争用。这由多种机制实现。 + + 例如,MOT不会在事务完成之前记录每个操作。它只在提交阶段记录,并且只记录更新的增量记录(不像基于磁盘的表那样的完整记录)。 + + 为了确保日志IO设备不会成为瓶颈,日志文件必须放在具有低延迟的驱动器上。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 有关配置的更多信息,请参阅[存储(MOT)](3-mot-deployment.md#存储mot)。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/3-mot-deployment.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/3-mot-deployment.md new file mode 100644 index 00000000..5c9ed606 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/3-mot-deployment.md @@ -0,0 +1,706 @@ +--- +title: MOT部署 +summary: MOT部署 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT部署 + +以下各小节介绍了各种必需和可选的设置,以达到最佳部署效果。 + +
+ +## MOT服务器优化:x86 + +通常情况下,数据库由以下组件绑定: + +- CPU:更快的CPU可以加速任何CPU绑定的数据库。 +- 磁盘:高速SSD/NVME可加速任何I/O绑定数据库。 +- 网络:更快的网络可以加速任何SQL*Net绑定数据库。 + +除以上内容外,以下通用服务器设置默认使用,可能会明显影响数据库的性能。 + +MOT性能调优是确保快速的应用程序功能和数据检索的关键步骤。MOT支持最新的硬件,因此调整每个系统以达到最大吞吐量是极为重要的。 + +以下是用于优化在英特尔x86服务器上运行MOT时的建议配置。这些设置是高吞吐量工作负载的最佳选择。 + +
+ +### BIOS + +- Hyper Threading设置为ON。 + + 强烈建议打开超线程(HT=ON)。 + + 建议在MOT上运行OLTP工作负载时打开超线程。当使用超线程时,某些OLTP工作负载显示高达40%的性能增益。 + +
+ +### 操作系统环境设置 + +- NUMA + + 禁用NUMA平衡,如下所示。MOT以极其高效的NUMA-aware方式进行内存管理,远远超过操作系统使用的默认方法。 + + ``` + echo 0 > /proc/sys/kernel/numa_balancing + ``` + +- 服务 + + 禁用如下服务: + + ``` + service irqbalance stop # MANADATORY + service sysmonitor stop # OPTIONAL, performance + service rsyslog stop # OPTIONAL, performance + ``` + +- 调优服务 + + 以下为必填项。 + + 服务器必须运行throughput-performance配置文件。 + + ``` + [...]$ tuned-adm profile throughput-performance + ``` + + throughput-performance配置文件是广泛适用的调优,它为各种常见服务器工作负载提供卓越的性能。 + + 其他不太适合MogDB和MOT服务器的配置可能会影响MOT的整体性能,包括:平衡配置、桌面配置、延迟性能配置、网络延迟配置、网络吞吐量配置和节能配置。 + +- 系统命令 + + 推荐使用下列操作系统设置以获得最佳性能。 + + - 在/etc/sysctl.conf文件中添加如下配置,然后执行sysctl -p命令: + + ``` + net.ipv4.ip_local_port_range = 9000 65535 + kernel.sysrq = 1 + kernel.panic_on_oops = 1 + kernel.panic = 5 + kernel.hung_task_timeout_secs = 3600 + kernel.hung_task_panic = 1 + vm.oom_dump_tasks = 1 + kernel.softlockup_panic = 1 + fs.file-max = 640000 + kernel.msgmnb = 7000000 + kernel.sched_min_granularity_ns = 10000000 + kernel.sched_wakeup_granularity_ns = 15000000 + kernel.numa_balancing=0 + vm.max_map_count = 1048576 + net.ipv4.tcp_max_tw_buckets = 10000 + net.ipv4.tcp_tw_reuse = 1 + net.ipv4.tcp_tw_recycle = 1 + net.ipv4.tcp_keepalive_time = 30 + net.ipv4.tcp_keepalive_probes = 9 + net.ipv4.tcp_keepalive_intvl = 30 + net.ipv4.tcp_retries2 = 80 + kernel.sem = 250 6400000 1000 25600 + net.core.wmem_max = 21299200 + net.core.rmem_max = 21299200 + net.core.wmem_default = 21299200 + net.core.rmem_default = 21299200 + #net.sctp.sctp_mem = 94500000 915000000 927000000 + #net.sctp.sctp_rmem = 8192 250000 16777216 + #net.sctp.sctp_wmem = 8192 250000 16777216 + net.ipv4.tcp_rmem = 8192 250000 16777216 + net.ipv4.tcp_wmem = 8192 250000 16777216 + net.core.somaxconn = 65535 + vm.min_free_kbytes = 26351629 + net.core.netdev_max_backlog = 65535 + net.ipv4.tcp_max_syn_backlog = 65535 + #net.sctp.addip_enable = 0 + net.ipv4.tcp_syncookies = 1 + vm.overcommit_memory = 0 + net.ipv4.tcp_retries1 = 5 + net.ipv4.tcp_syn_retries = 5 + ``` + + - 按如下方式修改/etc/security/limits.conf对应部分: + + ``` + soft nofile 100000 + hard nofile 100000 + ``` + + 软限制和硬限制设置可指定一个进程同时打开的文件数量。软限制可由各自运行这些限制的进程进行更改,直至达到硬限制值。 + +- 磁盘/SSD + + 下面以数据库同步提交模式为例,介绍如何保证磁盘读写性能适合数据库同步提交模式。 + + 按如下方式运行磁盘/SSD性能测试: + + ``` + [...]$ sync; dd if=/dev/zero of=testfile bs=1M count=1024; sync + 1024+0 records in + 1024+0 records out + 1073741824 bytes (1.1 GB) copied, 1.36034 s, 789 MB/s + ``` + + 当磁盘带宽明显低于789MB/s时,可能会造成MogDB性能瓶颈,尤其是造成MOT性能瓶颈。 + +
+ +### 网络 + +需要使用10Gbps以上网络。 + +运行iperf命令进行验证: + +``` +Server side: iperf -s +Client side: iperf -c +``` + +rc.local:网卡调优 + +以下可选设置对性能有显著影响: + +1. 将 下的set_irq_privacy.sh文件拷贝到/var/scripts/目录下。 + +2. 进入/etc/rc.d/rc.local,执行chmod命令,确保在boot时执行以下脚本: + + ``` + 'chmod +x /etc/rc.d/rc.local' + var/scripts/set_irq_affinity.sh -x all + ethtool -K gro off + ethtool -C adaptive-rx on adaptive-tx on + Replace with the network card, i.e. ens5f1 + ``` + +
+ +## MOT服务器优化:基于Arm的华为TaiShan2P/4P服务器 + +以下是基于Arm/鲲鹏架构的华为TaiShan 2280 v2服务器(2路256核)和TaiShan 2480 v2服务器(4路256核)上运行MOT时的建议配置。 + +除非另有说明,以下设置适用于客户端和服务器的机器。 + +
+ +### BIOS + +修改BIOS相关设置: + +1. 选择**BIOS**> **Advanced** > **MISC Config**。设置**Support Smmu**为**Disabled**。 + +2. 选择**BIOS**> **Advanced** > **MISC Config**。设置**CPU Prefetching Configuration**为**Disabled**。 + + ![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-deployment-1.png) + +3. 选择**BIOS**> **Advanced** > **Memory Config**。设置**Die Interleaving**为**Disabled**。 + + ![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-deployment-2.png) + +4. 选择**BIOS**> **Advanced** > **Performance Config**。设置**Power Policy**为**Performance**。 + + ![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-deployment-3.png) + +
+ +### 操作系统:内核和启动 + +- 以下操作系统内核和启动参数通常由sysadmin配置。 + + 配置内核参数,如下所示。 + + ```bash + net.ipv4.ip_local_port_range = 9000 65535 + kernel.sysrq = 1 + kernel.panic_on_oops = 1 + kernel.panic = 5 + kernel.hung_task_timeout_secs = 3600 + kernel.hung_task_panic = 1 + vm.oom_dump_tasks = 1 + kernel.softlockup_panic = 1 + fs.file-max = 640000 + kernel.msgmnb = 7000000 + kernel.sched_min_granularity_ns = 10000000 + kernel.sched_wakeup_granularity_ns = 15000000 + kernel.numa_balancing=0 + vm.max_map_count = 1048576 + net.ipv4.tcp_max_tw_buckets = 10000 + net.ipv4.tcp_tw_reuse = 1 + net.ipv4.tcp_tw_recycle = 1 + net.ipv4.tcp_keepalive_time = 30 + net.ipv4.tcp_keepalive_probes = 9 + net.ipv4.tcp_keepalive_intvl = 30 + net.ipv4.tcp_retries2 = 80 + kernel.sem = 32000 1024000000 500 32000 + kernel.shmall = 52805669 + kernel.shmmax = 18446744073692774399 + sys.fs.file-max = 6536438 + net.core.wmem_max = 21299200 + net.core.rmem_max = 21299200 + net.core.wmem_default = 21299200 + net.core.rmem_default = 21299200 + net.ipv4.tcp_rmem = 8192 250000 16777216 + net.ipv4.tcp_wmem = 8192 250000 16777216 + net.core.somaxconn = 65535 + vm.min_free_kbytes = 5270325 + net.core.netdev_max_backlog = 65535 + net.ipv4.tcp_max_syn_backlog = 65535 + net.ipv4.tcp_syncookies = 1 + vm.overcommit_memory = 0 + net.ipv4.tcp_retries1 = 5 + net.ipv4.tcp_syn_retries = 5 + ##NEW + kernel.sched_autogroup_enabled=0 + kernel.sched_min_granularity_ns=2000000 + kernel.sched_latency_ns=10000000 + kernel.sched_wakeup_granularity_ns=5000000 + kernel.sched_migration_cost_ns=500000 + vm.dirty_background_bytes=33554432 + kernel.shmmax=21474836480 + net.ipv4.tcp_timestamps = 0 + net.ipv6.conf.all.disable_ipv6=1 + net.ipv6.conf.default.disable_ipv6=1 + net.ipv4.tcp_keepalive_time=600 + net.ipv4.tcp_keepalive_probes=3 + kernel.core_uses_pid=1 + ``` + +- 调优服务 + + 以下为必填项。 + + 服务器必须运行throughput-performance配置文件: + + ```bash + [...]$ tuned-adm profile throughput-performance + ``` + + throughput-performance配置文件是广泛适用的调优,它为各种常见服务器工作负载提供卓越的性能。 + + 其他不太适合MogDB和MOT服务器的配置可能会影响MOT的整体性能,包括:平衡配置、桌面配置、延迟性能配置、网络延迟配置、网络吞吐量配置和节能配置。 + +- 启动调优 + + 在内核启动参数中添加iommu.passthrough=1。 + + 在pass-through模式下运行时,适配器需要DMA转换到内存,从而提高性能。 + +
+ +## MOT配置 + +预置MOT用于创建工作MOT。为了获得最佳效果,建议根据应用程序的特定要求和偏好自定义MOT配置(在mot.conf文件中定义)。 + +该文件在服务器启动时只读。如果在系统运行中编辑此文件,则必须重新加载服务器才能使修改内容生效。 + +mot.conf文件与postgres.conf配置文件在同一文件夹下。 + +阅读[总体原则](#总体原则),根据需要查看和配置mot.conf文件。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 以上描述了mot.conf文件中的各个设置。除上述内容外,要了解特定MOT功能(如恢复),可参考本用户手册的相关章节。例如,[MOT恢复](5-mot-administration.md#mot恢复)说明了mot.conf文件的恢复,包含影响MOT恢复的设置。此外,有关恢复的完整说明,请参阅“MOT管理”章节的[MOT恢复](5-mot-administration.md#mot恢复)。下文各相关章节中还提供了参考链接。 + +以下介绍了mot.conf文件中的各个部分,其包含的设置以及默认值。 + +
+ +### 总体原则 + +以下是编辑mot.conf文件的总体原则。 + +- 每个设置项都带有默认值,如下所示: + + ``` + # name = value + ``` + +- 可以接受空格或留空。 + +- 在各行添加#号可进行注释。 + +- 每个设置项的默认值将作为注释显示在整个文件中。 + +- 如果参数没有注释并且置入了新值,则定义新设置。 + +- 对mot.conf文件的更改仅在数据库服务器启动或重装时生效。 + +内存单元的表示如下: + +- KB:千字节 +- MB:兆字节 +- GB:吉字节 +- TB:太字节 + +某些内存单位为postgresql.conf中的max_process_memory的百分比值。例如,20%。 + +时间单位表示如下: + +- us:微秒 +- ms:毫秒 +- s:秒 +- min:分钟 +- h:小时 +- d:天 + +
+ +### 重做日志(MOT) + +- **enable_redo_log = true** + + 指定是否使用重做日志以获得持久性。有关重做日志的详细信息,请参阅[MOT日志记录:WAL重做日志](5-mot-administration.md#mot日志记录wal重做日志)。 + +- **enable_group_commit = false** + + 是否使用组提交。 + + 该选项仅在MogDB配置为使用同步提交时相关,即仅当postgresql.conf中的synchronization_commit设置为除off以外的任何值时相关。 + + 有关WAL重做日志的详细信息,请参阅[MOT日志记录:WAL重做日志](5-mot-administration.md#mot日志记录wal重做日志)。 + +- **group_commit_size = 16** + +- **group_commit_timeout = 10 ms** + + 只有当MOT引擎配置为同步组提交日志记录时,此选项才相关。即postgresql.conf中的synchronization_commit配置为true,mot.conf配置文件中的enable_group_commit配置为true。 + + 当一组事务记录在WAL重做日志中时,需确定以下设置项取值: + + group_commit_size:一组已提交的事务数。例如,16表示当同一组中的16个事务已由它们的客户端应用程序提交时,则针对16个事务中的每个事务,在磁盘的WAL重做日志中写入一个条目。 + + group_commit_timeout:超时时间,单位为毫秒。例如,10表示在10毫秒之后,为同一组由客户端应用程序在最近10毫秒内提交的每个事务,在磁盘的WAL重做日志中写入一个条目。 + + 提交组在到达配置的事务数后或者在超时后关闭。组关闭后,组中的所有事务等待一个组落盘完成执行,然后通知客户端每个事务都已经结束。 + + 有关同步组提交日志记录的详细信息,请参阅[MOT日志类型](5-mot-administration.md#mot日志类型)。 + +
+ +### 检查点(MOT) + +- **enable_checkpoint = true** + + 是否使用周期检查点。 + +- **checkpoint_dir =** + + 指定检查点数据存放目录。默认位置在每个数据节点的data文件夹中。 + +- **checkpoint_segsize = 16 MB** + + 指定检查点时使用的段大小。分段执行检查点。当一个段已满时,它将被序列化到磁盘,并为后续的检查点数据打开一个新的段。 + +- **checkpoint_workers = 3** + + 指定在检查点期间要使用的工作线程数。 + + 检查点由多个MOT引擎工作线程并行执行。工作线程的数量可能会大大影响整个检查点操作的整体性能,以及其它正在运行的事务的操作。为了实现较短的检查点持续时间,应使用更多线程,直至达到最佳数量(根据硬件和工作负载的不同而不同)。但请注意,如果这个数目太大,可能会对其他正在运行的事务的执行时间产生负面影响。尽可能低这个数字,以最小化对其他运行事务的运行时的影响。当此数目过高时,检查点持续时间会较长。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 有关配置的更多信息,请参阅[MOT检查点](5-mot-administration.md#mot检查点)。 + +
+ +### 恢复(MOT) + +- **checkpoint_recovery_workers = 3** + + 指定在检查点数据恢复期间要使用的工作线程数。每个MOT引擎工作线程在自己的核上运行,通过将不同的表读入内存,可以并行处理不同的表。缺省值为3,可将此参数设置为可处理的核数。恢复后,将停止并杀死这些线程。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 有关配置的详细信息,请参阅[MOT恢复](5-mot-administration.md#mot恢复)。 + +
+ +### 统计(MOT) + +- **enable_stats = false** + + 设置周期性统计打印信息。 + +- **print_stats_period = 10 minute** + + 设置汇总统计报表打印的时间范围。 + +- **print_full_stats_period = 1 hours** + + 设置全量统计报表打印的时间范围。 + + 以下设置为周期性统计报表中的各个部分。如果没有配置,则抑制统计报表。 + +- **enable_log_recovery_stats = false** + + 日志恢复统计信息包含各种重做日志的恢复指标。 + +- **enable_db_session_stats = false** + + 数据库会话统计信息包含事务事件,如提交、回滚等。 + +- **enable_network_stats = false** + + 网络统计信息包括连接/断连事件。 + +- **enable_log_stats = false** + + 日志统计信息包含重做日志详情。 + +- **enable_memory_stats = false** + + 内存统计信息包含内存层详情。 + +- **enable_process_stats = false** + + 进程统计信息包含当前进程的内存和CPU消耗总量。 + +- **enable_system_stats = false** + + 系统统计信息包含整个系统的内存和CPU消耗总量。 + +- **enable_jit_stats = false** + + JIT统计信息包含有关JIT查询编译和执行的信息。 + +
+ +### 错误日志(MOT) + +- **log_level = INFO** + + 设置MOT引擎下发的消息在数据库服务器的错误日志中记录的日志级别。有效值为PANIC、ERROR、WARN、INFO、TRACE、DEBUG、DIAG1、DIAG2。 + +- **Log/COMPONENT/LOGGER=LOG_LEVEL** + + 使用以下语法设置特定的日志记录器。 + + 例如,要为系统组件中的ThreadIdPool日志记录器配置TRACE日志级别,请使用以下语法: + + ``` + Log/System/ThreadIdPool=TRACE + ``` + + 要为某个组件下的所有记录器配置日志级别,请使用以下语法: + + ``` + Log/COMPONENT=LOG_LEVEL + ``` + + 例如: + + ``` + Log/System=DEBUG + ``` + +
+ +### 内存(MOT) + +- **enable_numa = true** + + 指定是否使用可识别NUMA的内存。 禁用时,所有亲和性配置也将被禁用。 MOT引擎假定所有可用的NUMA节点都有内存。 如果计算机具有某些特殊配置,其中某些NUMA节点没有内存,则MOT引擎初始化将因此失败,因此数据库服务器启动将失败。 在此类计算机中,建议将此配置值设置为false,以防止启动失败并让MOT引擎在不使用可识别NUMA的内存分配的情况下正常运行。 + +- **affinity_mode = fill-physical-first** + + 设置用户会话和内部MOT任务的线程亲和模式。 + + 使用线程池时,用户会话将忽略此值,因为它们的亲和性由线程池控制。但内部MOT任务仍然使用。 + + 有效值为fill-socket-first、equal-per-socket、fill-physical-first、none。 + + - Fill-socket-first将线程连接到同一个槽位的核上,直到槽位已满,然后移动到下一个槽位。 + - Equal-per-socket使线程均匀分布在所有槽位中。 + - Fill-physical-first将线程连接到同一个槽位中的物理核,直到用尽所有物理核,然后移动到下一个槽位。当所有物理核用尽时,该过程再次从超线程核开始。 + - None禁用任何亲和配置,并让系统调度程序确定每个线程调度在哪个核上运行。 + +- **lazy_load_chunk_directory = true** + + 设置块目录模式,用于内存块查找。 + + Lazy模式将块目录设置为按需加载部分目录,从而减少初始内存占用(大约从1GB减少到1MB)。然而,这可能会导致轻微的性能损失和极端情况下的内存损坏。相反,使用non-lazy块目录会额外分配1GB的初始内存,产生略高的性能,并确保在内存损坏期间避免块目录错误。 + +- **reserve_memory_mode = virtual** + + 设置内存预留模式(取值为physical或virtual)。 + + 每当从内核分配内存时,都会参考此配置值来确定所分配的内存是常驻(physical)还是非常驻(virtual)。这主要与预分配有关,但也可能影响运行时分配。对于physical保留模式,通过强制内存区域所跨越的所有页出现页错误,使整个分配的内存区域常驻。配置virtual内存预留可加速内存分配(特别是在预分配期间),但可能在初始访问期间出现页错误(因此导致轻微的性能影响),并在物理内存不可用时出现更多服务器错误。相反,物理内存分配速度较慢,但后续访问速度更快且有保障。 + +- **store_memory_policy = compact** + + 设置内存存储策略(取值为compact或expanding)。 + + 当定义了compact策略时,未使用的内存会释放回内核,直到达到内存下限(请参见下面的min_mot_memory)。在expanding策略中,未使用的内存存储在MOT引擎中,以便后续再使用。compact存储策略可以减少MOT引擎的内存占用,但偶尔会导致性能轻微下降。此外,在内存损坏时,它还可能导致内存不可用。相反,expanding模式会占用更多的内存,但是会更快地分配内存,并且能够更好地保证在解分配后能够重新分配内存。 + +- **chunk_alloc_policy = auto** + + 设置全局内存的块分配策略。 + + MOT内存以2MB的块为单位组织。源NUMA节点和每个块的内存布局会影响表数据在NUMA节点间的分布,因此对数据访问时间有很大影响。在特定NUMA节点上分配块时,会参考分配策略。 + + 可用值包括auto、local、page-interleaved、chunk-interleaved、native。 + + - Auto策略根据当前硬件情况选择块分配策略。 + - Local策略在各自的NUMA节点上分配每个数据块。 + - Page-interleaved策略从所有NUMA节点分配由交插内存4千字节页组成的数据块。 + - Chunk-interleaved策略以轮循调度方式从所有NUMA节点分配数据块。 + - Native策略通过调用原生系统内存分配器来分配块。 + +- **chunk_prealloc_worker_count = 8** + + 设置每个NUMA节点参与内存预分配的工作线程数。 + +- **max_mot_global_memory = 80%** + + 设置MOT引擎全局内存的最大限制。 + + 指定百分比值与postgresql.conf中max_process_memory定义的总量有关。 + + MOT引擎内存分为全局(长期)内存,主要用于存储用户数据,以及本地(短期)内存,主要用于用户会话,以满足本地需求。 + + 任何试图分配超出此限制的内存的尝试将被拒绝,并向用户报告错误。请确保max_mot_global_memory与max_mot_local_memory之和不超过postgresql.conf中配置的max_process_memory。 + +- **min_mot_global_memory = 0 MB** + + 设置MOT引擎全局内存的最小限制。 + + 指定百分比值与postgresql.conf中max_process_memory定义的总量有关。 + + 此值用于启动期间的内存预分配,以及确保MOT引擎在正常运行期间有最小的内存可用量。当使用compact存储策略时(参阅上文store_memory_policy),该值指定了下限,超过下限的内存不会释放回内核,而是保留在MOT引擎中以便后续重用。 + +- **max_mot_local_memory = 15%** + + 设置MOT引擎本地内存的最大限制。 + + 指定百分比值与postgresql.conf中max_process_memory定义的总量有关。 + + MOT引擎内存分为全局(长期)内存,主要用于存储用户数据,以及本地(短期)内存,主要用于用户会话,以满足本地需求。 + + 任何试图分配超出此限制的内存的尝试将被拒绝,并向用户报告错误。请确保max_mot_global_memory与max_mot_local_memory之和不超过postgresql.conf中配置的max_process_memory。 + +- **min_mot_local_memory = 0 MB** + + 设置MOT引擎本地内存的最小限制。 + + 指定百分比值与postgresql.conf中max_process_memory定义的总量有关。 + + 此值用于在启动期间预分配内存,以及确保MOT引擎在正常运行期间有最小的可用内存。当使用compact存储策略时(参阅上文store_memory_policy),该值指定了下限,超过下限的内存不会释放回内核,而是保留在MOT引擎中以便后续重用。 + +- **max_mot_session_memory = 0 MB** + + 设置MOT引擎中单个会话的最大内存限制。 + + 指定百分比值与postgresql.conf中max_process_memory定义的总量有关。 + + 通常,MOT引擎中的会话可以根据需要分配尽可能多的本地内存,只要没有超出本地内存限制即可。为了避免单个会话占用过多的内存,从而拒绝其他会话的内存,通过该配置项限制小会话的本地内存分配(最大1022KB)。 + + 请确保该配置项不影响大会话的本地内存分配。 + + 0表示不会限制每个小会话的本地分配,除非是由max_mot_local_memory配置的本地内存分配限制引起的。 + +- **min_mot_session_memory = 0 MB** + + 设置MOT引擎中单个会话的最小内存预留。 + + 指定百分比值与postgresql.conf中max_process_memory定义的总量有关。 + + 此值用于在会话创建期间预分配内存,以及确保会话有最小的可用内存量来执行其正常操作。 + +- **high_red_mark_percent = 90** + + 设置内存分配的高红标记。 + + 这是按照由max_mot_memory设置的MOT引擎的最大值百分比计算的。默认值为90,即90%。当MOT占用内存总量达到此值时,只允许进行破坏性操作。其它操作都向用户报告错误。 + +- **session_large_buffer_store_size = 0 MB** + + 设置会话的大缓冲区存储。 + + 当用户会话执行需要大量内存的查询时(例如,使用许多行),大缓冲区存储用于增加此类内存可用的确定级别,并更快地为这个内存请求提供服务。对于超过1022KB的会话,任何内存分配都是大内存分配。如果未使用或耗尽了大缓冲区存储,则这些分配将被视为直接从内核提供的巨大分配。 + +- **session_large_buffer_store_max_object_size = 0 MB** + + 设置会话的大分配缓冲区存储中的最大对象大小。 + + 大缓冲区存储内部被划分为不同大小的对象。此值用于对源自大缓冲区存储的对象设置上限,以及确定缓冲区存储内部划分为不同大小的对象。 + + 此大小不能超过session_large_buffer_store_size的1/8。如果超过,则将其调整到最大可能。 + +- **session_max_huge_object_size = 1 GB** + + 设置会话单个大内存分配的最大尺寸。 + + 巨大分配直接从内核中提供,因此不能保证成功。 + + 此值也适用于全局(非会话相关)内存分配。 + +
+ +### 垃圾收集(MOT) + +- **enable_gc = true** + + 是否使用垃圾收集器(Garbage Collector,GC)。 + +- **reclaim_threshold = 512 KB** + + 设置垃圾收集器的内存阈值。 + + 每个会话管理自己的待回收对象列表,并在事务提交时执行自己的垃圾回收。此值决定了等待回收的对象的总内存阈值,超过该阈值,会话将触发垃圾回收。 + + 一般来说,这里是在权衡未回收对象与垃圾收集频率。设置低值会使未回收的内存保持在较少的水平,但会导致频繁的垃圾回收,从而影响性能。设置高值可以减少触发垃圾回收的频率,但会导致未回收的内存过多。此设置取决于整体工作负载。 + +- **reclaim_batch_size = 8000** + + 设置垃圾回收的批次大小。 + + 垃圾收集器从对象中批量回收内存,以便限制在一次垃圾收集传递中回收的对象数量。此目的是最小化单个垃圾收集传递的操作时间。 + +- **high_reclaim_threshold = 8 MB** + + 设置垃圾回收的高内存阈值。 + + 由于垃圾收集是批量工作的,因此会话可能有许多可以回收的对象,但这些对象不能回收。在这种情况下,为了防止垃圾收集列表变得过于膨胀,尽管已经达到批处理大小限制,此值继续单独回收对象,直到待回收对象小于该阈值,或者没有更多符合回收条件的对象。 + +
+ +### JIT(MOT) + +- **enable_mot_codegen = true** + + 指定是否对计划查询使用JIT查询编译和执行。 + + JIT查询执行为在计划阶段准备好的查询准备了JIT编译的代码。每当调用准备好的查询时,都会执行生成的JIT编译函数。JIT编译通常以LLVM的形式进行。在原生不支持LLVM的平台上,MOT提供了基于软件的回退(Tiny Virtual Machine,TVM)。 + +- **force_mot_pseudo_codegen = false** + + 当前平台支持LLVM时,是否使用TVM(伪LLVM)。 + + 在原生不支持LLVM的平台上,MOT自动默认为TVM。 + + 在原生支持LLVM的平台上,默认使用LLVM。该配置项允许在支持LLVM的平台上使用TVM进行JIT编译和执行。 + +- **enable_mot_codegen_print = false** + + 指定是否为JIT编译的查询打印发出的LLVM/TVM IR代码。 + +- **mot_codegen_limit = 100** + + 限制每个用户会话允许的JIT查询数。 + +
+ +### 存储(MOT) + +**allow_index_on_nullable_column = true** + +指定是否允许在可空列上定义索引。 + +
+ +### 默认MOT.conf文件 + +最小设置和配置指定将Postgresql.conf文件指向MOT.conf文件的位置: + +``` +Postgresql.conf +mot_config_file = '/tmp/gauss/ MOT.conf' +``` + +确保max_process_memory设置的值足够包含MOT的全局(数据和索引)和本地(会话)内存。 + +MOT.conf的默认内容满足开始使用的需求。设置内容后续可以优化。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/4-mot-usage.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/4-mot-usage.md new file mode 100644 index 00000000..01738fbb --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/4-mot-usage.md @@ -0,0 +1,544 @@ +--- +title: MOT使用 +summary: MOT使用 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT使用 + +使用MOT非常简单,以下几个小节将会进行描述。 + +MogDB允许应用程序使用MOT和基于标准磁盘的表。MOT适用于最活跃、高竞争和对吞吐量敏感的应用程序表,也可用于所有应用程序的表。 + +以下命令介绍如何创建MOT,以及如何将现有的基于磁盘的表转换为MOT,以加速应用程序的数据库相关性能。MOT尤其有利于已证明是瓶颈的表。 + +以下是与使用MOT相关的任务的简单概述: + +- 授予用户权限 +- 创建/删除MOT +- 为MOT创建索引 +- 将磁盘表转换为MOT +- 查询原生编译 +- 重试中止事务 +- MOT外部支持工具 +- MOT SQL覆盖和限制 + +
+ +## 授予用户权限 + +以授予数据库用户对MOT存储引擎的访问权限为例。每个数据库用户仅执行一次,通常在初始配置阶段完成。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: MOT通过外部数据封装器(Foreign Data Wrapper,FDW)机制与MogDB数据库集成,所以需要授权用户权限。 + +要使特定用户能够创建和访问MOT(DDL、DML、SELECT),以下语句只执行一次: + +```sql +GRANT USAGE ON FOREIGN SERVER mot_server TO ; +``` + +所有关键字不区分大小写。 + +
+ +## 创建/删除MOT + +创建MOT非常简单。只有MOT中的创建和删除表语句与MogDB中基于磁盘的表的语句不同。SELECT、DML和DDL的所有其他命令的语法对于MOT表和MogDB基于磁盘的表是一样的。 + +- 创建MOT: + + ```sql + create FOREIGN table test(x int) [server mot_server]; + ``` + +- 以上语句中: + + - 始终使用FOREIGN关键字引用MOT。 + - 在创建MOT表时,[server mot_server]部分是可选的,因为MOT是一个集成的引擎,而不是一个独立的服务器。 + - 上文以创建一个名为test的内存表(表中有一个名为x的整数列)为例。在下一节(创建索引)中将提供一个更现实的例子。 + - 如果postgresql.conf中开启了增量检查点,则无法创建MOT。因此请在创建MOT前将enable_incremental_checkpoint设置为off。 + +- 删除名为test的MOT: + + ```sql + drop FOREIGN table test; + ``` + +有关MOT的功能限制(如数据类型),请参见[MOT SQL覆盖和限制](#mot-sql覆盖和限制)。 + +
+ +## 为MOT创建索引 + +支持标准的PostgreSQL创建和删除索引语句。 + +例如: + +```sql +create index text_index1 on test(x) ; +``` + +创建一个用于TPC-C的ORDER表,并创建索引: + +```sql +create FOREIGN table bmsql_oorder ( + o_w_id integer not null, + o_d_id integer not null, + o_id integer not null, + o_c_id integer not null, + o_carrier_id integer, + o_ol_cnt integer, + o_all_local integer, + o_entry_d timestamp, + primarykey (o_w_id, o_d_id, o_id) +); +create index bmsql_oorder_index1 on bmsql_oorder(o_w_id, o_d_id, o_c_id, o_id) ; +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 在MOT名字之前不需要指定FOREIGN关键字,因为它仅用于创建和删除表的命令。 + +有关MOT索引限制,请参见[MOT SQL覆盖和限制](#mot-sql覆盖和限制)的索引部分内容。 + +
+ +## 将磁盘表转换为MOT + +磁盘表直接转换为MOT尚不能实现,这意味着尚不存在将基于磁盘的表转换为MOT的ALTER TABLE语句。 + +下面介绍如何手动将基于磁盘的表转换为MOT,如何使用gs_dump工具导出数据,以及如何使用gs_restore工具导入数据。 + +
+ +### 前置条件检查 + +检查待转换为MOT的磁盘表的模式是否包含所有需要的列。 + +检查架构是否包含任何不支持的列数据类型,具体参见[不支持的数据类型](#不支持的数据类型)章节。 + +如果不支持特定列,则建议首先创建一个更新了模式的备磁盘表。此模式与原始表相同,只是所有不支持的类型都已转换为支持的类型。 + +使用以下脚本导出该备磁盘表,然后导入到MOT中。 + +
+ +### 转换 + +要将基于磁盘的表转换为MOT,请执行以下步骤: + +1. 暂停应用程序活动。 +2. 使用gs_dump工具将表数据转储到磁盘的物理文件中。请确保使用data only。 +3. 重命名原始基于磁盘的表。 +4. 创建同名同模式的MOT。请确保使用创建FOREIGN关键字指定该表为MOT。 +5. 使用gs_restore将磁盘文件的数据加载/恢复到数据库表中。 +6. 浏览或手动验证所有原始数据是否正确导入到新的MOT中。下面将举例说明。 +7. 恢复应用程序活动。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: 由于表名称保持不变,应用程序查询和相关数据库存储过程将能够无缝访问新的MOT,而无需更改代码。请注意,MOT目前不支持跨引擎多表查询(如使用Join、Union和子查询)和跨引擎多表事务。因此,如果在多表查询、存储过程或事务中访问原始表,则必须将所有相关的磁盘表转换为MOT,或者更改应用程序或数据库中的相关代码。 + +
+ +### 转换示例 + +假设要将数据库benchmarksql中一个基于磁盘的表customer迁移到MOT中。 + +将customer表迁移到MOT,操作步骤如下: + +1. 检查源表列类型。验证MOT支持所有类型,详情请参阅[不支持的数据类型](#不支持的数据类型)章节。 + + ```sql + benchmarksql-# \d+ customer + Table "public.customer" + Column | Type | Modifiers | Storage | Stats target | Description + --------+---------+-----------+---------+--------------+------------- + x | integer | | plain | | + y | integer | | plain | | + Has OIDs: no + Options: orientation=row, compression=no + ``` + +2. 请检查源表数据。 + + ```sql + benchmarksql=# select * from customer; + x | y + ---+--- + 1 | 2 + 3 | 4 + (2 rows) + ``` + +3. 只能使用gs_dump转储表数据。 + + ```sql + $ gs_dump -Fc benchmarksql -a --table customer -f customer.dump + gs_dump[port='15500'][benchmarksql][2020-06-04 16:45:38]: dump database benchmarksql successfully + gs_dump[port='15500'][benchmarksql][2020-06-04 16:45:38]: total time: 332 ms + ``` + +4. 重命名源表。 + + ```sql + benchmarksql=# alter table customer rename to customer_bk; + ALTER TABLE + ``` + +5. 创建与源表完全相同的MOT。 + + ```sql + benchmarksql=# create foreign table customer (x int, y int); + CREATE FOREIGN TABLE + benchmarksql=# select * from customer; + x | y + ---+--- + (0 rows) + ``` + +6. 将源转储数据导入到新MOT中。 + + ```sql + $ gs_restore -C -d benchmarksql customer.dump + restore operation successful + total time: 24 ms + Check that the data was imported successfully. + benchmarksql=# select * from customer; + x | y + ---+--- + 1 | 2 + 3 | 4 + (2 rows) + + benchmarksql=# \d + List of relations + Schema | Name | Type | Owner | Storage + --------+-------------+---------------+--------+---------------------------------- + public | customer | foreign table | aharon | + public | customer_bk | table | aharon | {orientation=row,compression=no} + (2 rows) + ``` + +
+ +## 查询原生编译 + +MOT的另一个特性是,在预编译的完整查询需要执行之前,能够以原生格式(使用PREPARE语句)准备并解析这些查询。 + +这种原生格式方便后续更有效地执行(使用EXECUTE命令)。这种执行类型速度要快得多,因为原生格式在执行期间绕过多个数据库处理层,从而获得更好的性能。 + +这种分工避免了重复的解析分析操作。查询和事务语句可以交互执行。此功能有时称为即时(Just-In-Time,JIT)查询编译。 + +
+ +### 查询编译:PREPARE语句 + +若要使用MOT的原生查询编译,请在执行查询之前调用PREPARE客户端语句。MOT将预编译查询和(或)从缓存预加载先前预编译的代码。 + +下面是SQL中PREPARE语法的示例: + +```sql +PREPARE name [ ( data_type [, ...] ) ] AS statement +``` + +PREPARE在数据库服务器中创建一个预处理语句,该语句是一个可用于优化性能的服务器端对象。 + +
+ +### 运行命令 + +发出EXECUTE命令时,将解析、分析、重写和执行预处理语句。这种分工避免了重复的解析分析操作,同时使执行计划依赖于特定的设置值。 + +下面是在Java应用程序中调用PREPARE和EXECUTE语句的示例。 + +```sql +conn = DriverManager.getConnection(connectionUrl, connectionUser, connectionPassword); + +// Example 1: PREPARE without bind settings +String query = "SELECT * FROM getusers"; +PreparedStatement prepStmt1 = conn.prepareStatement(query); +ResultSet rs1 = pstatement.executeQuery()) +while (rs1.next()) {…} + +// Example 2: PREPARE with bind settings +String sqlStmt = "SELECT * FROM employees where first_name=? and last_name like ?"; +PreparedStatement prepStmt2 = conn.prepareStatement(sqlStmt); +prepStmt2.setString(1, "Mark"); // first name “Mark” +prepStmt2.setString(2, "%n%"); // last name contains a letter “n” +ResultSet rs2 = prepStmt2.executeQuery()) +while (rs2.next()) {…} +``` + +MOT编译支持的特性和不支持的特性见下文。 + +
+ +### 轻量执行支持的查询 + +以下查询类型适合轻量执行: + +- 简单点查询 + - SELECT (including SELECT for UPDATE) + - UPDATE + - DELETE +- INSERT查询 +- 引用主键的完整前缀的范围UPDATE查询 +- 引用主键的完整前缀的范围SELECT查询 +- JOIN查询,其中一部分或两部分重叠为点查询 +- 引用每个连接表中主键的完整前缀的JOIN查询 + +
+ +### 轻量执行不支持的查询 + +任何特殊的查询属性都不适用于轻量执行。特别是如果以下条件中的任何一项适用,则该查询不适合轻量执行。有关更多信息,请参阅[原生编译和轻量执行不支持的查询](#原生编译和轻量执行不支持的查询)。 + +需要强调一点,如果查询语句不适用原生编译和轻量执行,不向客户端报告错误,查询仍以正常和规范的方式执行。 + +有关MOT原生编译功能的详细信息,请参阅[查询原生编译](#查询原生编译)的有关内容。 + +
+ +## 重试中止事务 + +在乐观并发控制(OCC)中,在COMMIT阶段前的事务期间(使用任何隔离级别)不会对记录进行锁定。这是一个能显著提高性能的强大优势。它的缺点是,如果另一个会话尝试更新相同的记录,则更新可能会失败。所以必须中止整个事务。这些所谓的更新冲突是由MOT在提交时通过版本检查机制检测到的。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 使用悲观并发控制的引擎,如标准Postgres和MogDB基于磁盘的表,当使用SERIALIZABLE或REPEATABLE-READ隔离级别时,也会发生类似的异常中止。 + +这种更新冲突在常见的OLTP场景中非常少见,在使用MOT时尤其少见。但是,由于仍有可能发生这种情况,开发人员应该考虑使用事务重试代码来解决此问题。 + +下面以多个会话同时尝试更新同一个表为例,说明如何重试表命令。有关更多详细信息,请参阅[OCC与2PL的区别举例](../../../administrator-guide/mot-engine/3-concepts-of-mot/3-2.md#occ与2pl的区别举例)部分。下面以TPC-C支付事务为例。 + +```sql +int commitAborts = 0; + +while (commitAborts < RETRY_LIMIT) { + + try { + stmt =db.stmtPaymentUpdateDistrict; + stmt.setDouble(1, 100); + stmt.setInt(2, 1); + stmt.setInt(3, 1); + stmt.executeUpdate(); + + db.commit(); + + break; + } + catch (SQLException se) { + if(se != null && se.getMessage().contains("could not serialize access due to concurrent update")) { + log.error("commmit abort = " + se.getMessage()); + commitAborts++; + continue; + }else { + db.rollback(); + } + + break; + } +} +``` + +
+ +## MOT外部支持工具 + +为了支持MOT,修改了以下外部MogDB工具。请确保使用的工具是最新版本。下面将介绍与MOT相关的用法。有关这些工具及其使用方法的完整说明,请参阅《参考指南》中的“工具参考”章节。 + +
+ +### gs_ctl(全量和增量) + +此工具用于从主服务器创建备服务器,以及当服务器的时间线偏离后,将服务器与其副本进行同步。 + +在操作结束时,工具将获取最新的MOT检查点,同时考虑checkpoint_dir配置值。 + +检查点从源服务器的checkpoint_dir读取到目标服务器的checkpoint_dir。 + +目前MOT不支持增量检查点。因此,gs_ctl增量构建对于MOT来说不是以增量方式工作,而是以全量方式工作。Postgres磁盘表仍然可以增量构建。 + +
+ +### gs_basebackup + +gs_basebackup用于准备运行中服务器的基础备份,不影响其他数据库客户端。 + +MOT检查点也会在操作结束时获取。但是,检查点的位置是从源服务器中的checkpoint_dir获取的,并传输到源数据目录中,以便正确备份。 + +
+ +### gs_dump + +gs_dump用于将数据库模式和数据导出到文件中。支持MOT。 + +
+ +### gs_restore + +gs_restore用于从文件中导入数据库模式和数据。支持MOT。 + +
+ +## MOT SQL覆盖和限制 + +MOT设计几乎能够覆盖SQL和未来特性集。例如,大多数支持标准的Postgres SQL,也支持常见的数据库特性,如存储过程、自定义函数等。 + +下面介绍各种SQL覆盖和限制。 + +
+ +### 不支持的特性 + +MOT不支持以下特性: + +- 跨引擎操作:不支持跨引擎(磁盘+MOT)的查询、视图或事务。计划于2021年实现该特性。 +- MVCC、隔离:不支持没有快照/可序列化隔离。计划于2021年实现该特性。 +- 原生编译(JIT):SQL覆盖有限。此外,不支持存储过程的JIT编译。 +- 本地内存限制为1GB。一个事务只能更改小于1GB的数据。 +- 容量(数据+索引)受限于可用内存。未来将提供Anti-caching和数据分层功能。 +- 不支持全文检索索引。 +- 不支持逻辑复制特性。 + +此外,下面详细列出了MOT、MOT索引、查询和DML语法的各种通用限制,以及查询原生编译的特点和限制。 + +
+ +### MOT限制 + +MOT功能限制: + +- 按范围分区 +- AES加密 +- 流操作 +- 自定义类型 +- 子事务 +- DML触发器 +- DDL触发器 +- “C”或“POSIX”以外的排序规则 + +
+ +### 不支持的DDL操作 + +- 修改表结构 +- 创建including表 +- 创建as select表 +- 按范围分区 +- 创建无日志记录子句(no-logging clause)的表 +- 创建可延迟约束主键(DEFERRABLE) +- 重新索引 +- 表空间 +- 使用子命令创建架构 + +
+ +### 不支持的数据类型 + +- UUID +- User-Defined Type (UDF) +- Array data type +- NVARCHAR2(n) +- NVARCHAR(n) +- Clob +- Name +- Blob +- Raw +- Path +- Circle +- Reltime +- Bit varying(10) +- Tsvector +- Tsquery +- JSON +- HSTORE +- Box +- Text +- Line +- Point +- LSEG +- POLYGON +- INET +- CIDR +- MACADDR +- Smalldatetime +- BYTEA +- Bit +- Varbit +- OID +- Money +- 无限制的varchar/character varying +- HSTORE +- XML + +
+ +### 不支持的索引DDL和索引 + +- 在小数和数值类型上创建索引 + +- 在可空列上创建索引 + +- 单表创建索引总数>9 + +- 在键大小>256的表上创建索引 + + 键大小包括以字节为单位的列大小+列附加大小,这是维护索引所需的开销。下表列出了不同列类型的列附加大小。 + + 此外,如果索引不是唯一的,额外需要8字节。 + + 下面是伪代码计算键大小: + + ```sql + keySize =0; + + for each (column in index){ + keySize += (columnSize + columnAddSize); + } + if (index is non_unique) { + keySize += 8; + } + ``` + + | 列类型 | 列大小 | 列附加大小 | + | :------- | :----- | :--------- | + | varchar | N | 4 | + | tinyint | 1 | 1 | + | smallint | 2 | 1 | + | int | 4 | 1 | + | longint | 8 | 1 | + | float | 4 | 2 | + | double | 8 | 3 | + +上表中未指定的类型,列附加大小为零(例如时间戳)。 + +
+ +### 不支持的DML + +- Merge into +- Select into +- Lock table +- Copy from table + +
+ +### 原生编译和轻量执行不支持的查询 + +- 查询涉及两个以上的表 +- 查询有以下任何一个情况: + - 非原生类型的聚合 + - 窗口功能 + - 子查询子链接 + - Distinct-ON修饰语(distinct子句来自DISTINCT ON) + - 递归(已指定WITH RECURSIVE) + - 修改CTE(WITH中有INSERT/UPDATE/DELETE) + +以下子句不支持轻量执行: + +- Returning list +- Group By clause +- Grouping sets +- Having clause +- Windows clause +- Distinct clause +- Sort clause that does not conform to native index order +- Set operations +- Constraint dependencies diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/5-mot-administration.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/5-mot-administration.md new file mode 100644 index 00000000..283a1d27 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/5-mot-administration.md @@ -0,0 +1,456 @@ +--- +title: MOT管理 +summary: MOT管理 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT管理 + +下面介绍MOT管理。 + +
+ +## MOT持久性 + +持久性是指长期的数据保护(也称为磁盘持久化)。持久性意味着存储的数据不会遭受任何形式的退化或损坏,因此数据不会丢失或损坏。持久性可确保在有计划停机(例如维护)或计划外崩溃(例如电源故障)后数据和MOT引擎恢复到一致状态。 + +内存存储是易失的,需要电力来维护所存储的信息。另一方面,磁盘存储是非易失性的,这意味着它不需要电源来维护存储的信息,因此不用担心停电。MOT同时使用这两种类型的存储。内存中存储了所有数据,同时将事务性更改持久化到磁盘,并保持频繁的定期[MOT检查点](#mot检查点),以确保在关机时恢复数据。 + +用户必须保证有足够的磁盘空间用于日志记录和检查点操作。检查点使用单独的驱动器,通过减少磁盘I/O负载来提高性能。 + +参考[MOT关键技术](../../../administrator-guide/mot-engine/1-introducing-mot/3-mot-key-technologies.md)了解如何在MOT引擎中实现持久化。 + +若要设置持久性: + +为保证严格一致性,请在postgres.conf配置文件中将参数sync_commit配置为On。 + +MOT的WAL重做日志和检查点开启持久性,下面将详细介绍。 + +
+ +### MOT日志记录:WAL重做日志 + +为保证持久性,MOT全面集成MogDB的WAL机制,通过MogDB的XLOG接口持久化WAL记录。这意味着,每次MOT记录的添加、更新和删除都记录在WAL中。确保了可以从这个非易失性日志重新生成和恢复最新的数据状态。例如,如果向表中添加了3行,删除了2行,更新了1行,那么日志中将记录6个条目。 + +MOT日志记录和MogDB磁盘表的其他记录写入同一个WAL中。 + +MOT只记录事务提交阶段的操作。 + +MOT只记录更新的增量记录,以便最小化写入磁盘的数据量。 + +在恢复期间,从最后一个已知或特定检查点加载数据;然后使用WAL重做日志完成从该点开始发生的数据更改。 + +WAL重做日志将保留所有表行修改,直到执行检查点(如上所述)。然后可以截断日志,以减少恢复时间和节省磁盘空间。 + +注意:为确保日志IO设备不会成为瓶颈,日志文件必须放在具有低延迟的驱动器上。 + +
+ +### MOT日志类型 + +支持两个同步事务日志选项和一个异步事务日志选项(标准MogDB磁盘引擎也支持这些选项)。MOT还支持同步的组提交日志记录与NUMA-aware优化,如下所述。 + +根据您的配置,实现以下类型的日志记录: + +- **同步重做日志记录** + + 同步重做日志记录选项是最简单、最严格的重做日志记录器。当客户端应用程序提交事务时,事务重做条目记录在WAL重做日志中,如下所示: + + 1. 当事务正在进行时,它存储在MOT内存中。 + + 2. 事务完成后,客户端应用程序发送Commit命令,该事务被锁定,然后写入磁盘上的WAL重做日志。当事务日志条目写入日志时,客户端应用程序仍在等待响应。 + + 3. 一旦事务的整个缓冲区被写入日志,就更改内存中的数据,然后提交事务。事务提交后,通知客户端应用程序事务完成。 + + **总结** + + 同步重做日志记录选项是最安全、最严格的,因为它确保了客户端应用程序和每个事务提交时的WAL重做日志条目的完全同步,从而确保了总的持久性和一致性,并且绝对不会丢失数据。此日志记录选项可防止客户端应用程序在事务尚未持久化到磁盘时将事务标记为成功的情况。 + + 同步重做日志记录选项的缺点是,它是三个选项中最慢的日志机制。因为客户端应用程序必须等待所有数据都写入磁盘,并且磁盘写入过于频繁导致数据库变慢。 + +- **组同步重做日志记录** + + 组同步重做日志记录选项与同步重做日志记录选项非常相似,它确保完全持久性,绝对不会丢失数据,并保证客户端应用程序和WAL重做日志条目的完全同步。不同的是,组同步重做日志记录选项将事务重做条目组同时写入磁盘上的WAL重做日志,而不是在提交时写入每个事务。使用组同步重做日志记录可以减少磁盘I/O数量,从而提高性能,特别是在运行繁重的工作负载时。 + + MOT引擎通过根据运行事务的核的NUMA槽位自动对事务进行分组,使用NUMA感知优化来执行同步的组提交记录。 + + 有关NUMA-aware内存访问的更多信息,请参阅[NUMA-aware分配和亲和性](../../../administrator-guide/mot-engine/3-concepts-of-mot/3-4.md)。 + + 当一个事务提交时,一组条目记录在WAL重做日志中,如下所示: + + 1. 当事务正在进行时,它存储在内存中。MOT引擎根据运行事务的核的NUMA槽位对桶中的事务进行分组。在同一槽位上运行的所有事务都被分组在一起,并且多个组将根据事务运行的核并行填充。 + + 这样,将事务写入WAL更为有效,因为来自同一个槽位的所有缓冲区都一起写入磁盘。 + + 注意:每个线程在属于单槽位的单核/CPU上运行,每个线程只写在各自运行的核的槽位上。 + + 2. 在事务完成并且客户端应用程序发送Commit命令之后,事务重做日志条目将与同组的其他事务一起序列化。 + + 3. 当特定一组事务满足配置条件后,如[重做日志(MOT)](3-mot-deployment.md#重做日志mot)小节中描述的已提交的事务数或超时时间,该组中的事务将被写入磁盘的WAL中。当这些日志条目被写入日志时,发出提交请求的客户端应用程序正在等待响应。 + + 4. 一旦NUMA-aware组中的所有事务缓冲区都写入日志,该组中的所有事务都将对内存存储执行必要的更改,并且通知客户端这些事务已完成。 + + **总结** + + 组同步重做日志记录选项是一个极其安全和严格的日志记录选项,因为它确保了客户端应用程序和WAL重做日志条目的完全同步,从而确保了总的持久性和一致性,而且绝对不会丢失数据。此日志记录选项可防止客户端应用程序在事务尚未持久化到磁盘时将事务标记为成功的情况。 + + 该选项的磁盘写入次数比同步重做日志记录选项少,这可能意味着它更快。缺点是事务被锁定的时间更长。在同一NUMA内存中的所有事务都写入磁盘的WAL重做日志之前,它们一直处于锁定状态。 + + 是否使用此选项取决于事务工作负载的类型。例如,此选项有利于事务较多的系统。而对于事务少的系统而言,磁盘写入量也很少,因此不建议使用。 + +- **异步重做日志记录** + + 异步重做日志记录选项是最快的日志记录方法,但是它不能确保数据不会丢失,某些仍位于缓冲区中且尚未写入磁盘的数据在电源故障或数据库崩溃时可能会丢失。当客户端应用程序提交事务时,事务重做条目将记录在内部缓冲区中,并按预先配置的时间间隔写入磁盘。客户端应用程序不会等待数据写入磁盘。它将继续进行下一个事务。这就是异步重做日志记录最快的原因。 + + 当客户端应用程序提交事务时,事务重做条目记录在WAL重做日志中,如下所示: + + 1. 当事务正在进行时,它存储在MOT内存中。 + + 2. 在事务完成并且客户端应用程序发送Commit命令后,事务重做条目将被写入内部缓冲区,但尚未写入磁盘。然后更改MOT数据内存,并通知客户端应用程序事务已提交。 + + 3. 后台运行的重做日志线程按预先配置的时间间隔收集所有缓存的重做日志条目,并将它们写入磁盘。 + + **总结** + + 异步重做日志记录选项是最快的日志记录选项,因为它不需要客户端应用程序等待数据写入磁盘。此外,它将许多事务重做条目分组并把它们写入一起,从而减少降低MOT引擎速度的磁盘I/O数量。 + + 异步重做日志记录选项的缺点是它不能确保在崩溃或失败时数据不会丢失。已提交但尚未写入磁盘的数据在提交时是不持久的,因此在出现故障时无法恢复。异步重做日志记录选项对于愿意牺牲数据恢复(一致性)而不是性能的应用程序来说最为适用。 + +
+ +### 配置日志 + +标准MogDB磁盘引擎支持两个同步事务日志选项和一个异步事务日志选项。 + +配置日志记录 + +1. 在postgres.conf配置文件中的sync_commit (On = Synchronous)参数中指定是否执行同步或异步事务日志记录。 +2. 在重做日志章节中的mot.conf配置文件里,将enable_redo_log参数设置为True。 + +如果已选择事务日志记录的同步模式(如上文所述,synchronous_commit = On),则在mot.conf配置文件中的enable_group_commit参数中指定Group Synchronous Redo Logging选项或Synchronous Redo Logging选项。如果选择Group Synchronous Redo Logging,必须在mot.conf文件中定义以下阈值,决定何时将一组事务记录在WAL中。 + +- group_commit_size:一组已提交的事务数。例如,16表示当同一组中的16个事务已由它们的客户端应用程序提交时,则针对16个事务中的每个事务,在磁盘的WAL重做日志中写入一个条目。 +- group_commit_timeout:超时时间,单位为毫秒。例如,10表示在10毫秒之后,为同一组由客户端应用程序在最近10毫秒内提交的每个事务,在磁盘的WAL重做日志中写入一个条目。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 有关配置的详细信息,请参阅[重做日志(MOT)](3-mot-deployment.md#重做日志mot)。 + +
+ +### MOT检查点 + +检查点是一个时间点。在这个时间点,表行的所有数据都保存在持久存储上的文件中,以便创建完整持久的数据库镜像。这是一个数据在某个时间点的快照。 + +检查点减少了为确保持久性而必须重放的WAL重做日志条目的数量,以此缩短数据库的恢复时间。检查点还减少了保存所有日志条目所需的存储空间。 + +如果没有检查点,那么为了恢复数据库,所有WAL重做条目必须从开始时间进行重放,可能需要几天或几周的时间,这取决于数据库中的记录数量。检查点记录数据库的当前状态,并允许丢弃旧的重做条目。 + +检查点在恢复方案(特别是冷启动)中是必不可少的。首先,从最后一个已知或特定检查点加载数据;然后使用WAL完成此后发生的数据更改。 + +例如,如果同一表行被修改100次,则日志中将记录100个条目。当使用检查点后,即使表行被修改了100次,检查点也可以一次性记录。在记录检查点之后,可以基于该检查点执行恢复,并且只需要播放自该检查点之后发生的WAL重做日志条目。 + +
+ +## MOT恢复 + +MOT恢复的主要目标是在有计划停机(例如维护)或计划外崩溃(例如电源故障后)后,将数据和MOT引擎恢复到一致状态。 + +MOT恢复是随着MogDB数据库其余部分的恢复而自动执行的,并且完全集成到MogDB恢复过程(也称为冷启动)。 + +MOT恢复包括两个阶段: + +检查点恢复:必须通过将数据加载到内存行并创建索引,从磁盘上的最新检查点文件恢复数据。 + +WAL重做日志恢复:从检查点恢复中使用检查点后,必须通过重放之后添加到日志中的记录,从WAL重做日志中恢复最近的数据(在检查点中未捕获)。 + +MogDB管理和触发WAL重做日志恢复。 + +- 配置恢复。 +- 虽然WAL恢复以串行方式执行,但可以将检查点恢复配置为以多线程方式运行(即由多个工作线程并行运行)。 +- 在mot.conf文件中配置Checkpoint_recovery_workers参数,见[恢复(MOT)](3-mot-deployment.md#恢复mot)中的描述。 + +
+ +## MOT复制和高可用 + +由于MOT集成到MogDB中,并且使用或支持其复制和高可用,因此,MOT原厂功能即支持同步复制和异步复制。 + +MogDB gs_ctl工具用于可用性控制和数据库操作。这包括gs_ctl切换、gs_ctl故障切换、gs_ctl构建等等。 + +有关更多信息,请参见MogDB参考指南。 + +- 配置复制和高可用性。 +- 请参考MogDB相关文档。 + +
+ +## MOT内存管理 + +规划和微调请参见[MOT内存和存储规划](2-mot-preparation.md#mot内存和存储规划)和[MOT配置](3-mot-deployment.md#mot配置)。 + +
+ +## MOT VACUUM清理 + +使用VACUUM进行垃圾收集,并有选择地分析数据库,如下所示。 + +- 【Postgres】 + + 在Postgres中,VACUUM用于回收死元组占用的存储空间。在正常的Postgres操作中,删除的元组或因更新而作废的元组不会从表中物理删除。只能由VACUUM清理。因此,需要定期执行VACUUM,特别是在频繁更新的表上。 + +- 【MOT扩展】 + + MOT不需要周期性的VACUUM操作,因为新元组会重用失效元组和空元组。只有当MOT的大小急剧减少,并且不计划恢复到原来大小时,才需要VACUUM操作。 + + 例如,应用程序定期(如每周一次)大量删除表数据的同时插入新数据,这需要几天时间,并且不一定是相同数量的行。在这种情况下,可以使用VACUUM。 + + 对MOT的VACUUM操作总是被转换为带有排他表锁的VACUUM FULL。 + +- 支持的语法和限制 + + 按规范激活VACUUM操作。 + + ```sql + VACUUM [FULL | ANALYZE] [ table ]; + ``` + + 只支持FULL和ANALYZE VACUUM两种类型。VACUUM操作只能对整个MOT进行。 + + 不支持以下Postgres VACUUM选项: + + - FREEZE + - VERBOSE + - Column specification + - LAZY模式(部分表扫描) + + 此外,不支持以下功能: + + - AUTOVACUUM + +
+ +## MOT统计 + +统计信息主要用于性能分析或调试。在生产环境中,通常不打开它们(默认是关闭的)。统计信息主要由数据库开发人员使用,数据库用户较少使用。 + +对性能有一定影响,特别是对服务器。对用户的影响可以忽略不计。 + +统计信息保存在数据库服务器日志中。该日志位于data文件夹中,命名为postgresql-DATE-TIME.log。 + +有关详细的配置选项,请参阅[统计(MOT)](3-mot-deployment.md#统计mot)。 + +
+ +## MOT监控 + +监控的所有语法支持基于Postgres的FDW表,包括下面的表或索引大小。此外,还存在用于监控MOT内存消耗的特殊函数,包括MOT全局内存、MOT本地内存和单个客户端会话。 + +
+ +### 表和索引大小 + +可以通过查询pg_relation_size来监控表和索引的大小。 + +例如: + +**数据大小** + +```sql +select pg_relation_size('customer'); +``` + +**索引** + +```sql +select pg_relation_size('customer_pkey'); +``` + +
+ +### MOT全局内存详情 + +检查MOT全局内存大小,主要是数据和索引。 + +```sql +select * from mot_global_memory_detail(); +``` + +结果如下。 + +```sql +numa_node | reserved_size | used_size +----------------+----------------+------------- +-1 | 194716368896 | 25908215808 +0 | 446693376 | 446693376 +1 | 452984832 | 452984832 +2 | 452984832 | 452984832 +3 | 452984832 | 452984832 +4 | 452984832 | 452984832 +5 | 364904448 | 364904448 +6 | 301989888 | 301989888 +7 | 301989888 | 301989888 +``` + +其中, + +- -1为总内存。 +- 0-7为NUMA内存节点。 + +
+ +### MOT本地内存详情 + +检查MOT本地内存大小,包括会话内存。 + +```sql +select * from mot_local_memory_detail(); +``` + +结果如下。 + +```sql +numa_node | reserved_size | used_size +----------------+----------------+------------- +-1 | 144703488 | 144703488 +0 | 25165824 | 25165824 +1 | 25165824 | 25165824 +2 | 18874368 | 18874368 +3 | 18874368 | 18874368 +4 | 18874368 | 18874368 +5 | 12582912 | 12582912 +6 | 12582912 | 12582912 +7 | 12582912 | 12582912 +``` + +其中, + +- -1为总内存。 +- 0-7为NUMA内存节点。 + +
+ +### 会话内存 + +会话管理的内存从MOT本地内存中获取。 + +所有活动会话(连接)的内存使用量可以通过以下查询。 + +```sql +select * from mot_session_memory_detail(); +``` + +结果如下。 + +```sql +sessid | total_size | free_size | used_size +----------------------------------------+-----------+----------+---------- +1591175063.139755603855104 | 6291456 | 1800704 | 4490752 +``` + +其中, + +- total_size:分配给会话的内存。 +- free_size:未使用的内存。 +- used_size:使用中的内存。 + +DBA可以通过以下查询确定当前会话使用的本地内存状态。 + +```sql +select * from mot_session_memory_detail() + where sessid = pg_current_sessionid(); +``` + +结果如下。 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-administration-1.png) + +
+ +## MOT错误消息 + +错误可能由多种场景引起。所有错误都记录在数据库服务器日志文件中。此外,与用户相关的错误作为对查询、事务或存储过程执行或数据库管理操作的响应的一部分返回给用户。 + +- 服务器日志中报告的错误包括函数、实体、上下文、错误消息、错误描述和严重性。 +- 向用户报告的错误被翻译成标准PostgreSQL错误码,可能由MOT特定的消息和描述组成。 + +错误提示、错误描述和错误码见下文。该错误码实际上是内部代码,不记录也不返回给用户。 + +
+ +### 写入日志文件的错误 + +所有错误都记录在数据库服务器日志文件中。以下列出了写入数据库服务器日志文件但未返回给用户的错误。该日志位于data文件夹中,命名为postgresql-DATE-TIME.log。 + +**表 1** 只写入日志文件的错误 + +| 日志消息 | 内部错误代码 | +| :---------------------------------- | :------------------------------- | +| Error code denoting success | MOT_NO_ERROR 0 | +| Out of memory | MOT_ERROR_OOM 1 | +| Invalid configuration | MOT_ERROR_INVALID_CFG 2 | +| Invalid argument passed to function | MOT_ERROR_INVALID_ARG 3 | +| System call failed | MOT_ERROR_SYSTEM_FAILURE 4 | +| Resource limit reached | MOT_ERROR_RESOURCE_LIMIT 5 | +| Internal logic error | MOT_ERROR_INTERNAL 6 | +| Resource unavailable | MOT_ERROR_RESOURCE_UNAVAILABLE 7 | +| Unique violation | MOT_ERROR_UNIQUE_VIOLATION 8 | +| Invalid memory allocation size | MOT_ERROR_INVALID_MEMORY_SIZE 9 | +| Index out of range | MOT_ERROR_INDEX_OUT_OF_RANGE 10 | +| Error code unknown | MOT_ERROR_INVALID_STATE 11 | + +
+ +### 返回给用户的错误 + +下面列出了写入数据库服务器日志文件并返回给用户的错误。 + +MOT使用返回码(Return Code,RC)返回Postgres标准错误代码至封装。某些RC会导致向正在与数据库交互的用户生成错误消息。 + +MOT从内部返回Postgres代码(见下文)到数据库包,数据库封装根据标准的Postgres行为对其做出反应。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 提示信息中的%s、%u、%lu指代相应的错误信息(如查询、表名或其他信息)。 - %s:字符串 - %u:数字 - %lu:数字 + +**表 2** 返回给用户并记录到日志文件的错误 + +| 返回给用户的短/长描述 | Postgres代码 | 内部错误码 | +| :---------------------------------- | :------------------------------ | :------------------------------ | +| Success.Denotes success | ERRCODE*SUCCESSFUL*COMPLETION | RC_OK = 0 | +| FailureUnknown error has occurred. | ERRCODE_FDW_ERROR | RC_ERROR = 1 | +| Unknown error has occurred.Denotes aborted operation. | ERRCODE_FDW_ERROR | RC_ABORT | +| Column definition of %s is not supported.Column type %s is not supported yet. | ERRCODE_INVALID_COLUMN_DEFINITION | RC_UNSUPPORTED_COL_TYPE | +| Column definition of %s is not supported.Column type Array of %s is not supported yet. | ERRCODE_INVALID_COLUMN_DEFINITION | RC_UNSUPPORTED_COL_TYPE_ARR | +| Column size %d exceeds max tuple size %u.Column definition of %s is not supported. | ERRCODE_FEATURE_NOT_SUPPORTED | RC_EXCEEDS_MAX_ROW_SIZE | +| Column name %s exceeds max name size %u.Column definition of %s is not supported. | ERRCODE_INVALID_COLUMN_DEFINITION | RC_COL_NAME_EXCEEDS_MAX_SIZE | +| Column size %d exceeds max size %u.Column definition of %s is not supported. | ERRCODE_INVALID_COLUMN_DEFINITION | RC_COL_SIZE_INVLALID | +| Cannot create table.Cannot add column %s; as the number of declared columns exceeds the maximum declared columns. | ERRCODE_FEATURE*NOT*SUPPORTED | RC_TABLE_EXCEEDS*MAX*DECLARED_COLS | +| Cannot create index.Total column size is greater than maximum index size %u. | ERRCODE_FDW_KEY*SIZE*EXCEEDS_MAX_ALLOWED | RC_INDEX_EXCEEDS_MAX_SIZE | +| Cannot create index.Total number of indexes for table %s is greater than the maximum number of indexes allowed %u. | ERRCODE_FDW_TOO*MANY*INDEXES | RC_TABLE_EXCEEDS_MAX_INDEXES | +| Cannot execute statement.Maximum number of DDLs per transaction reached the maximum %u. | ERRCODE_FDW_TOO*MANY*DDL_CHANGES*IN*TRANSACTION*NOT*ALLOWED | RC_TXN_EXCEEDS_MAX_DDLS | +| Unique constraint violationDuplicate key value violates unique constraint \“%s\“”.Key %s already exists. | ERRCODE*UNIQUE*VIOLATION | RC_UNIQUE_VIOLATION | +| Table \“%s\” does not exist. | ERRCODE_UNDEFINED_TABLE | RC_TABLE_NOT_FOUND | +| Index \“%s\” does not exist. | ERRCODE_UNDEFINED_TABLE | RC_INDEX_NOT_FOUND | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_LOCAL_ROW_FOUND | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_LOCAL_ROW_NOT_FOUND | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_LOCAL_ROW_DELETED | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_INSERT_ON_EXIST | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_INDEX_RETRY_INSERT | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_INDEX_DELETE | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_LOCAL_ROW_NOT_VISIBLE | +| Memory is temporarily unavailable. | ERRCODE_OUT_OF_LOGICAL_MEMORY | RC_MEMORY_ALLOCATION_ERROR | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_ILLEGAL_ROW_STATE | +| Null constraint violated.NULL value cannot be inserted into non-null column %s at table %s. | ERRCODE_FDW_ERROR | RC_NULL_VIOLATION | +| Critical error.Critical error: %s. | ERRCODE_FDW_ERROR | RC_PANIC | +| A checkpoint is in progress - cannot truncate table. | ERRCODE_FDW_OPERATION_NOT_SUPPORTED | RC_NA | +| Unknown error has occurred. | ERRCODE_FDW_ERROR | RC_MAX_VALUE | +| <recovery message> | | ERRCODE_CONFIG_FILE_ERROR | +| <recovery message> | | ERRCODE_INVALID*TABLE*DEFINITION | +| Memory engine - Failed to perform commit prepared. | | ERRCODE_INVALID*TRANSACTION*STATE | +| Invalid option <option name> | | ERRCODE_FDW_INVALID*OPTION*NAME | +| Invalid memory allocation request size. | | ERRCODE_INVALID*PARAMETER*VALUE | +| Memory is temporarily unavailable. | | ERRCODE_OUT_OF*LOGICAL*MEMORY | +| Could not serialize access due to concurrent update. | | ERRCODE_T_R*SERIALIZATION*FAILURE | +| Alter table operation is not supported for memory table.Cannot create MOT tables while incremental checkpoint is enabled.Re-index is not supported for memory tables. | | ERRCODE_FDW_OPERATION*NOT*SUPPORTED | +| Allocation of table metadata failed. | | ERRCODE_OUT_OF_MEMORY | +| Database with OID %u does not exist. | | ERRCODE_UNDEFINED_DATABASE | +| Value exceeds maximum precision: %d. | | ERRCODE_NUMERIC_VALUE*OUT*OF_RANGE | +| You have reached a maximum logical capacity %lu of allowed %lu. | | ERRCODE_OUT_OF*LOGICAL*MEMORY | diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/6-mot-sample-tpcc-benchmark.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/6-mot-sample-tpcc-benchmark.md new file mode 100644 index 00000000..3dfccd65 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/2-using-mot/6-mot-sample-tpcc-benchmark.md @@ -0,0 +1,116 @@ +--- +title: MOT样例TPC-C基准 +summary: MOT样例TPC-C基准 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT样例TPC-C基准 + +## TPC-C简介 + +TPC-C基准是衡量联机事务处理(OLTP)系统性能的行业标准基准。它基于一个复杂的数据库和许多不同的事务类型。这些事务类型在此基准上执行。TPC-C基准测试既不依赖硬件,也不依赖软件,因此可以在每个测试平台上运行。基准模型的官方概述,见[tpc.org网站](http://www.tpc.org/default5.asp)。 + +该数据库由9个不同结构的表组成,因此也包括9种类型的数据。每个表的数据大小和数量不同。在数据库上混合执行五种不同类型和复杂性的并发事务。这些大部分是在线事务或者部分排队等待延迟批处理。由于这些表竞争有限的系统资源,许多系统组件都有压力,数据更改以各种方式执行。 + +**表 1** TPC-C数据库结构 + +| 表 | 条目数 | +| :------- | :------------------- | +| 仓库 | n | +| 供货商品 | 100,000 | +| 库存 | n x 100,000 | +| 地区 | n x 10 | +| 客户 | 3000/区,30,000/仓库 | +| 订单 | 客户数量(初始值) | +| 新增订单 | 30%订单(初始值) | +| 定单分录 | ~10/单 | +| 历史记录 | 客户数量(初始值) | + +事务组合代表从订单输入到订单交付的完整业务处理。具体来说,所提供的组合旨在产生相等数量的新订单事务和支付事务,并且为每十个新订单事务产生一个交付事务、一个订单状态事务和一个库存水平事务。 + +**表 2** TPC-C事务比例 + +| 事务级别≥4% | 占所有事务份额 | +| :---------- | :------------- | +| TPC-C新订单 | ≤ 45% | +| 支付 | ≥ 43% | +| 订单状态 | ≥ 4% | +| 交付 | ≥4%(批次) | +| 库存水平 | ≥ 4% | + +有两种方法来执行事务:作为存储过程(允许更高的吞吐量)和以标准交互式SQL模式执行。 + +**性能指标:tpm-C** + +tpm-C指标是每分钟执行的新订单事务数。考虑到事务中所需的组合以及广泛的复杂性和类型,此指标最接近地模拟一个全面的业务活动,而不仅仅是一个或两个事务或计算机操作。因此,tpm-C指标被认为是业务吞吐量的指标。 + +tpm-C指标单位表示为每分钟事务数-C,而C表示TPC-C特定基准。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 官方TPC-C基准规范可访问[此页面](http://www.tpc.org/tpc_documents_current_versions/pdf/tpc-c_v5.11.0.pdf)。本规范中的一些规则在行业中难以实现,因为对行业现状来说这些规则太严格了。例如:扩容规则(a) tpm-C/Warehouse必须大于9且小于12.86(要达到较高的tpm-C率,需要很高的仓库费率。这就意味着需要非常大的数据库和内存容量)以及规则(b)10倍终端*仓库(意味着大量的模拟客户端)。 + +## 系统级优化 + +请按照[MOT部署](3-mot-deployment.md)中的说明进行操作。下面介绍MogDB数据库在华为TaiShan服务器和Euler 2.8操作系统上部署时系统级的关键优化点,以达到极致性能。 + +## BenchmarkSQL:开源TPC-C工具 + +可以使用BenchmarkSQL测试TPCC,如下所示: + +- 下载benchmarksql:[https://osdn.net/frs/g_redir.php?m=kent&f=benchmarksql%2Fbenchmarksql-5.0.zip](https://osdn.net/frs/g_redir.php?m=kent&f=benchmarksql/benchmarksql-5.0.zip) +- benchmarksql工具中的模式创建脚本需要调整为MOT语法,避免使用不支持的DDL。下载调整后的脚本:。该tar文件的内容包括sql.common.mogdb.mot文件夹和jTPCCTData.java文件,以及一个示例配置文件postgresql.conf和TPCC属性文件props.mot供参考。 +- 将sql.common.mogdb.mot文件夹放在run文件夹下与sql.common同级的文件夹,用下载的Java文件替换src/client/jTPCCTData.java文件。 +- 编辑run文件夹下的runDatabaseBuild.sh文件,将extraHistID从AFTER_LOAD列表中删除,以避免不支持的ALTER表DDL。 +- 将lib/postgres文件夹下的JDBC驱动替换为openGauss JDBC。驱动下载链接:。 + +在下载的Java文件(与原始文件相比)中所做的唯一更改是注释错误日志打印,以进行序列化和重复键错误。这些错误在MOT中是正常的,因为MOT使用的是乐观并发控制(OCC)机制。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 基准测试使用标准交互式SQL模式执行,没有存储过程。 + +## 运行基准 + +任何人都可以启动服务器,运行benchmarksql脚本。 + +运行基准测试: + +1. 进入benchmarksql运行文件夹,将sql.common重命名为sql.common.orig。 +2. 创建sql.common到sql.common.mogdb.mot的链接,用于测试MOT。 +3. 启动数据库服务器。 +4. 配置客户端props.pg文件。 +5. 运行基准测试。 + +## 结果报告 + +- CLI结果 + + BenchmarkSQL结果应如下所示: + + ![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-sample-tpcc-benchmark-1.jpg) + + 随着时间的推移,基准测量并平均已提交的事务。上面的例子是两分钟的基准测试。 + + 得分为271万tmp-C(每分钟新增订单数),占总承诺事务数的45%,即tpmTOTAL。 + +- 详细结果报告 + + 详细结果报告示例: + +**图 1** 详细结果报告 + +![详细结果报告](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-sample-tpcc-benchmark-2.png) + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-sample-tpcc-benchmark-3.png) + +BenchmarkSQL收集详细的性能统计数据和操作系统性能数据(如果配置了的话)。 + +这些信息可以显示查询的延迟,从而暴露与存储/网络/CPU相关的瓶颈。 + +华为TaiShan 2480 MOT TPC-C测试结果 + +2020年5月1日TPC-C基准测试,TaiShan 2480服务器(Arm/鲲鹏4路服务器)安装MogDB数据库,吞吐量达到479万tpmC。 + +下图展示了近乎线性的可扩展性: + +**图 2** 华为TaiShan 2480 MOT TPC-C测试结果 + +![华为TaiShan-2480-MOT-TPC-C测试结果](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-sample-tpcc-benchmark-4.png) diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-1.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-1.md new file mode 100644 index 00000000..2f653b29 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-1.md @@ -0,0 +1,95 @@ +--- +title: MOT纵向扩容架构 +summary: MOT纵向扩容架构 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT纵向扩容架构 + +纵向扩容即为同一台机器添加额外的核以增加算力。纵向扩容是传统上为单对控制器和多核的机器增加算力的常见形式。纵向扩容架构受限于控制器的可扩展性。 + +
+ +## 技术要求 + +MOT旨在实现以下目标: + +- **线性扩容**:MOT提供事务性存储引擎,利用单个NUMA架构服务器的所有核,以提供近线性的扩容性能。这意味着MOT的目标是在机器的核数和性能提升倍数之间实现直接的、近线性的关系。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: MOT的近线性扩容效果明显优于所有现有方案,并且尽可能接近于获得最佳效果,因现有方案皆受限于硬件(如电线)的物理限制和局限性。 + +- **无最大核数限制**:MOT对最大核数不做任何限制。这意味着MOT可从单核扩展到高达1000秒的多核,并且新增的核退化速度最小,即便是在跨NUMA槽位边界的情况下。 +- **极高的事务性吞吐量**:MOT提供了一个事务性存储引擎,与市场上任何其他OLTP供应商相比,它能够实现极高的事务性吞吐量。 +- **极低的事务性时延**:与市场上任何其他OLTP供应商相比,MOT提供事务性存储引擎,可以达到极低的事务时延。 +- **无缝集成和利用MogDB产品**:MOT事务引擎与MogDB产品标准无缝集成。通过这种方式,MOT最大限度地重用了位于其事务性存储引擎顶部的MogDB层功能。 + +
+ +## 设计原则 + +为了实现上述要求(特别是在多核的环境中),我们存储引擎的体系结构实施了以下技术和策略: + +- 数据和索引只存在于内存中。 +- 数据和索引不用物理分区来布局(因为对于某些类型的应用程序,这些分区的性能可能会降低)。 +- 事务并发控制基于乐观并发控制(OCC),没有集中的争用点。有关OCC的详细信息,请参见[MOT并发控制机制](3-2.md)。 +- 使用平行重做日志(最后单位为核)来有效避免中央锁定点。 +- 使用免锁索引。有关免锁索引的详细信息,请参见[MOT索引](3-5.md)。 +- 使用NUMA感知内存分配,避免跨槽位访问,特别是会话生命周期对象。有关NUMA感知的更多信息,请参见[NUMA-aware分配和亲和性](3-4.md)。 +- 使用带有预缓存对象池的自定义MOT内存管理分配器,避免昂贵的运行时间分配和额外的争用点。这种专用的MOT内存分配器按需预先访问操作系统中较大的内存块,然后按需将内存分配给MOT,使内存分配更加高效。 + +
+ +## 使用外部数据封装(FDW)进行集成 + +MOT遵循并利用了MogDB的标准扩展机制 - 外部数据封装(FDW),如下图所示。 + +在PostgreSQL外部数据封装特性的支持下,作为其他数据源的代理的MOT数据库可以创建外表,如MySQL、Oracle、PostgreSQL等。当对外表执行查询时,FDW将查询外部数据源并返回结果,就像查询内表一样。 + +MogDB依赖PostgreSQL外部数据封装和索引支持,因此SQL完全覆盖,包括存储过程、用户定义函数、系统函数调用。 + +**图 1** MOT架构 + +![MOT架构](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-scale-up-architecture-1.png) + +上图中绿色表示MOT引擎,蓝色表示现有的MogDB(基于Postgres)组件。由此可见,FDW在MOT引擎和MogDB组件之间进行中介。 + +**与MOT相关的FDW定制** + +通过FDW集成MOT可以重用最上层的MogDB功能,从而显著缩短MOT的上市时间,同时不影响SQL的覆盖范围。 + +但是,MogDB中原有的FDW机制并不是为存储引擎扩展而设计的,因此缺少以下基本功能: + +- 查询规划阶段待计算的外表的索引感知 +- 完整的DDL接口 +- 完整的事务生命周期接口 +- 检查点接口 +- 重做日志接口 +- 恢复接口 +- 真空接口 + +为了支持所有缺失的功能,SQL层和FDW接口层已扩展,从而为插入MOT事务存储引擎提供必要的基础设施。 + +
+ +## 结果:线性扩容 + +以下是上述MOT设计原则和实现的结果: + +MOT在符合ACID工作负载的事务吞吐量方面优于所有现有的工业级OLTP数据库。 + +MogDB和MOT在以下多核系统上进行了测试,性能可扩展性良好。在x86架构Intel和ARM/鲲鹏架构的多核服务器上进行了测试。详细的性能评估请参见[MOT性能基准](../../../administrator-guide/mot-engine/1-introducing-mot/5-mot-performance-benchmarks.md)。 + +以2020年6月的TPC-C基准测试了一台泰山2480服务器上的MogDB MOT数据库(4路ARM/鲲鹏服务器,吞吐量:480万tpmC)。下图显示了MOT数据库的近线性性质,即MOT数据库通过增加核数显著提高性能。 + +**图 2** ARM上的TPC-C(256核) + +![ARM上的TPC-C(256核)](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-3.png) + +下面是另一个测试示例,一台基于x86的服务器上也显示了CPU使用率。 + +**图 3** tpmC 对比CPU使用率 + +![tpmC-对比CPU使用率](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-performance-benchmarks-9.png) + +图表显示,MOT性能提高与核数增加有显著的相关性。随着核数的增加,MOT对CPU的消耗也越来越大。其他行业解决方案不能提高MOT性能,有时性能甚至略有下降,影响客户的CAPEX和OPEX支出以及运营效率。这是数据库行业的公认问题。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-2.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-2.md new file mode 100644 index 00000000..799e91f2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-2.md @@ -0,0 +1,191 @@ +--- +title: MOT并发控制机制 +summary: MOT并发控制机制 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT并发控制机制 + +通过大量研究,我们找到了最佳的并发控制机制,结论为:基于SILO的OCC算法是MOT中最符合ACID特性的OCC算法。SILO为满足MOT的挑战性需求提供了最好的基础。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: MOT完全符合原子性、一致性、隔离性、持久性(ACID)特性,如[MOT简介](../../../administrator-guide/mot-engine/1-introducing-mot/1-mot-introduction.md)所述。 + +下面介绍MOT的并发控制机制。 + +
+ +## MOT本地内存和全局内存 + +SILO管理本地内存和全局内存,如图1所示。 + +- 全局内存是所有核共享的长期内存,主要用于存储所有的表数据和索引。 +- 本地内存是短期内存,主要由会话使用,用于处理事务及将数据更改存储到事务内存中,直到提交阶段。 + +当事务需要更改时,SILO将该事务的所有数据从全局内存复制到本地内存。使用OCC方法,全局内存中放置的是最小的锁,因此争用时间极短。事务更改完成后,该数据从本地内存回推到全局内存中。 + +本地内存与SILO增强并发控制的基本交互式事务流如下所示: + +**图 1** 私有(本地)内存(每个事务)和全局内存(所有核的所有事务) + +![私有(本地)内存(每个事务)和全局内存(所有核的所有事务)](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-concurrency-control-mechanism-1.png) + +具体请参见[对比:磁盘与MOT](3-9.md)。 + +
+ +## MOT SILO增强特性 + +SILO凭借其基本算法流程,优于我们在研究实验中测试的许多其他符合ACID的OCC算法。然而,为了使SILO成为产品级机制,我们必须用许多在最初设计中缺失的基本功能来增强它,例如: + +- 新增对交互式事务的支持,其中事务的SQL运行在客户端实现,而不是作为服务器端的单个步骤运行。 +- 新增乐观插入 +- 新增对非唯一索引的支持 +- 新增对事务中写后读校验(RAW)的支持,使用户能够在提交之前查看更改 +- 新增对无锁协同垃圾回收的支持 +- 新增对无锁检查点的支持 +- 新增对快速恢复的支持 +- 新增对分布式部署两阶段提交的支持 + +在不破坏原始SILO的可扩展特性的前提下添加这些增强是非常具有挑战性的。 + +
+ +## MOT隔离级别 + +即使MOT完全兼容ACID,MogDB 2.1并非支持所有的隔离级别。下表介绍了各隔离级别,以及MOT支持和不支持的内容。 + +**表 1** 隔离级别 + +| 隔离级别 | 说明 | +| :--------------- | :----------------------------------------------------------- | +| READ UNCOMMITTED | **MOT不支持** | +| READ COMMITTED | **MOT支持**
READ COMMITTED(读已提交)隔离级别保证任何正在读取的数据在上一次读取时都已提交。它只是限制读者看到任何中间数据、未提交数据,或脏读。数据被读取后可以自由更改,因此,读已提交隔离级别并不保证事务再次读取时能找到相同的数据。 | +| SNAPSHOT | **MOT不支持**
SNAPSHOT(快照)隔离级别提供与SERIALIZABLE(可序列化)相同的保证,同时支持并发事务修改数据。相反,它迫使每个读者看到自己的世界版本(自己的快照)。不阻止并发更新使得编程非常容易,且可扩展性很强。然而,在许多实现中,这种隔离级别需要更高的服务器资源。 | +| REPEATABLE READ | **MOT支持**
REPEATABLE READ(可重复读)是一个更高的隔离级别,除了READ COMMITTED隔离级别的保证之外,它还保证任何读取的数据都不能更改。如果一个事务再次读取相同的数据,它将找出该数据,不做更改,并且保证它可读取。乐观模型使得并发事务能更新该事务读取的行。在提交时,该事务将验证REPEATABLE READ隔离级别是否被违反。若违反,则回滚该事务,必须重试。 | +| SERIALIZABLE | **MOT不支持**
SERIALIZABLE(可序列化)隔离提供了更强的保证。除了REPEATABLE READ隔离级别保证的所有内容外,它还保证后续读取不会看到新数据。它之所以被命名为SERIALIZABLE,是因为隔离非常严格,几乎有点像事务串行运行,而不是并行运行。 | + +下表显示了不同隔离级别启用的并发副作用。 + +**表 2** 隔离级别启用的并发副作用 + +| 隔离级别 | 说明 | 不可重复读 | 幻影 | +| :--------------- | :--- | :--------- | :--- | +| READ UNCOMMITTED | 是 | 是 | 是 | +| READ COMMITTED | 否 | 是 | 是 | +| REPEATABLE READ | 否 | 否 | 是 | +| SNAPSHOT | 否 | 否 | 否 | +| SERIALIZABLE | 否 | 否 | 否 | + +在不久后将发布的版本中,MogDB MOT还将支持SNAPSHOT和SERIALIZABLE隔离级别。 + +
+ +## MOT乐观并发控制 + +并发控制模块(简称CC模块)提供了主内存引擎的所有事务性需求。CC模块的主要目标是为主内存引擎提供各种隔离级别的支持。 + +
+ +### 乐观OCC与悲观2PL + +悲观2PL(2阶段锁定)和乐观并发控制(OCC)的功能差异在于对事务完整性分别采用悲观和乐观方法。 + +基于磁盘的表使用悲观方法,这是最常用的数据库方法。MOT引擎使用的是乐观方法。 + +悲观方法和乐观方法的主要功能区别在于,如果冲突发生, + +- 悲观的方法会导致客户端等待; +- 而乐观方法会导致其中一个事务失败,使得客户端必须重试失败的事务。 + +**乐观并发控制方法(MOT使用)** + +乐观并发控制(OCC)方法在冲突发生时检测冲突,并在提交时执行验证检查。 + +乐观方法开销较小,而且通常效率更高,原因之一是事务冲突在大多数应用程序中并不常见。 + +当强制执行REPEATABLE READ隔离级别时,乐观方法与悲观方法之间的函数差异更大,而当强制执行SERIALIZABLE隔离级别时,函数差异最大。 + +**悲观方法(MOT未使用)** + +悲观并发控制(2PL,或称2阶段锁定)方法使用锁阻止在潜在冲突的发生。执行语句时应用锁,提交事务时释放锁。基于磁盘的行存储使用这种方法,并且添加了多版本并发控制(Multi-version Concurrency Control,MVCC)。 + +在2PL算法中,当一个事务正在写入行时,其他事务不能访问该行;当一个行正在读取时,其他事务不能覆盖该行。在访问时锁定每个行,以进行读写;在提交时释放锁。这些算法需要一个处理和避免死锁的方案。死锁可以通过计算等待图中的周期来检测。死锁可以通过使用TSO保持时序或使用某种回退方案来避免。 + +**遇时锁定(ETL)** + +另一种方法是遇时锁定(ETL),它以乐观的方式处理读取,但写入操作锁定它们访问的数据。因此,来自不同ETL事务的写入操作相互感知,并可以决定中止。实验证明,ETL通过两种方式提高OCC的性能: + +- 首先,ETL会在早期检测冲突,并通常能增加事务吞吐量。这是因为事务不会执行无用的操作。(通常)在提交时发现的冲突无法在不中止至少一个事务的情况下解决。 +- 其次,ETL写后读校验(RAW)运行高效,无需昂贵或复杂的机制。 + +**结论:** + +OCC是大多数工作负载最快的选项。这一点我们在初步研究阶段已经发现。 + +其中一个原因是,当每个核执行多个线程时,锁很可能被交换线程持有,特别是在交互模式下。另一个原因是悲观算法涉及死锁检测(产生开销),并通常使用读写锁(比标准自旋锁效率低)。 + +我们选择Silo是因为它比其他现有选项(如TicToc)简单,同时对大多数工作负载保持相同的性能。ETL有时比OCC更快,但它引入了假中止,可能会使用户混淆,而OCC则只在提交时中止。 + +
+ +### OCC与2PL的区别举例 + +下面是会话同时更新同一个表时,两种用户体验的区别:悲观(针对基于磁盘的表)和乐观(针对MOT表)。 + +本例中,使用如下表测试命令: + +``` +table “TEST” - create table test (x int, y int, z int, primary key(x)); +``` + +本示例描述同一测试的两个方面:用户体验(本示例中的操作)和重试要求。 + +**悲观方法示例 - 用于基于磁盘的表** + +下面是一个悲观方法例子(非MOT)。任何隔离级别都可能适用。 + +以下两个会话执行尝试更新单个表的事务。 + +WAIT LOCK操作发生,客户端体验是:会话2卡住,直到会话1完成COMMIT,会话2才能进行。 + +但是,使用这种方法时,两个会话都成功,并且不会发生异常中止(除非应用了SERIALIZABLE或REPEATABLE-READ隔离级别),这会导致整个事务需要重试。 + +**表 3** 悲观方法代码示例 + +| | 会话1 | 会话2 | +| :--- | :------------------------------- | :----------------------------------------------------------- | +| t0 | Begin | Begin | +| t1 | update test set y=200 where x=1; | | +| t2 | y=200 | Update test set y=300 where x=1; - Wait on lock | +| t4 | Commit | | +| | | Unlock | +| | | Commit(in READ-COMMITTED this will succeed, in SERIALIZABLE it will fail) | +| | | y = 300 | + +**乐观方法示例 - 用于MOT** + +下面是一个乐观方法的例子。 + +它描述了创建一个MOT表,然后有两个并发会话同时更新同一个MOT表的情况。 + +``` +create foreign table test (x int, y int, z int, primary key(x)); +``` + +- OCC的优点是,在COMMIT之前没有锁。 +- OCC的缺点是,如果另一个会话更新了相同的记录,则更新可能会失败。如果更新失败(在所有支持的隔离级别中),则必须重试整个会话#2事务。 +- 更新冲突由内核在提交时通过版本检查机制检测。 +- 会话2将不会等待其更新操作,并且由于在提交阶段检测到冲突而中止。 + +**表 4** 乐观方法代码示例--用于MOT + +| | 会话1 | 会话2 | +| :--- | :------------------------------- | :------------------------------- | +| t0 | Begin | Begin | +| t1 | update test set y=200 where x=1; | | +| t2 | y=200 | Update test set y=300 where x=1; | +| t4 | Commit | y = 300 | +| | | Commit | +| | | ABORT | +| | | y = 200 | diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-3.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-3.md new file mode 100644 index 00000000..3975056b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-3.md @@ -0,0 +1,71 @@ +--- +title: 扩展FDW与其他MogDB特性 +summary: 扩展FDW与其他MogDB特性 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 扩展FDW与其他MogDB特性 + +MogDB基于PostgreSQL,而PostgreSQL没有内置存储引擎适配器,如MySQL的handlerton。为了使MOT存储引擎能够集成到MogDB中,我们利用并扩展了现有的FDW机制。随着FDW引入PostgreSQL 9.1,现在可以将这些外表和数据源呈现为统一、本地可访问的关系来访问外部管理的数据库。 + +和PostgreSQL不同的是,MOT存储引擎是嵌入在MogDB内部的,表由MogDB管理。MogDB规划器和执行器控制表的访问。MOT从MogDB获取日志和检查点服务,并参与MogDB恢复过程和其他过程。 + +我们把正在使用或正在访问MOT存储引擎的所有组件称为封装。 + +下图显示了MOT存储引擎如何嵌入到MogDB中及其对数据库功能的双向访问。 + +**图 1** MogDB内置MOT存储引擎-外部数据库的FDW访问 + +![MOT架构](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-scale-up-architecture-1.png) + +我们通过扩展和修改FdwRoutine结构来扩展FDW的能力,以便引入在MOT引入之前不需要的特性和调用。例如,新增了对以下功能的支持:添加索引、删除索引/表、截断、真空和表/索引内存统计。重点放在了FdwRoutine结构与MogDB日志、复制和检查点机制的集成,以便通过故障为跨表事务提供一致性。在这种情况下,MOT本身有时会通过FDW层发起对MogDB功能的调用。 + +
+ +## 创建表和索引 + +为了支持MOT表的创建,重用了标准的FDW语法。 + +例如,创建FOREIGN表。 + +MOT DW机制将指令传递给MOT存储引擎,用于实际建表。同样,我们支持创建索引(create index …)。此功能以前在FDW中不可用,因为表由外部管理,不需要此功能。 + +为了在MOT FDW中支持两者,ValidateTableDef函数实际上创建了指定的表。它还处理该关系的索引创建,DROP TABLE和DROP INDEX,以及先前在FDW中不支持的VACUUM和ALTER TABLE。 + +
+ +## 索引规划与执行的使用方法 + +查询分为两个阶段:规划和执行。在规划阶段(可能在多次执行中才出现一次),选择扫描的最佳索引。该选择基于匹配查询的WHERE子句、JOIN子句和ORDER BY条件。在执行期间,查询迭代相关的表行,并执行各种任务,如每次迭代的更新或删除。插入是一种特殊情况-表将行添加到所有索引中,且不需要扫描。 + +- **规划器**:在标准FDW中,将查询传递给外部数据源执行。这意味着索引过滤和实际规划(例如索引的选择)不在数据库中本地执行,而是在外部数据源中执行。在内部,FDW向数据库规划器返回总体计划。MOT表的处理方式与磁盘表类似。这意味着相关的MOT索引得到过滤和匹配,最小化遍历行集的索引被选择并添加到计划中。 +- **执行器**:查询执行器使用所选的MOT索引来迭代表的相关行。每个行都由MogDB封装检查,根据查询条件调用update或delete处理相应的行。 + +
+ +## 持久性、复制性和高可用性 + +存储引擎负责存储、读取、更新和删除底层内存和存储系统中的数据。存储引擎不处理日志、检查点和恢复,特别是因为某些事务包含多个不同存储引擎的表。因此,为了数据持久化和复制,MogDB封装使用如下高可用性设施: + +- **持久性**:MOT引擎通过WAL记录使数据持久化,WAL记录使用MogDB的XLOG接口。这为MogDB提供了使用相同API进行复制的好处。具体请参见[MOT持久性概念](3-6.md)。 +- **检查点设定**:通过向MogDB Checkpointer注册回调来启用MOT检查点每当执行通用数据库检查点时,MOT检查点也被调用。MOT保留了检查点的日志序列号(LSN),以便与MogDB恢复对齐。MOT Checkpointing算法是高度优化的异步算法,不会停止并发事务。具体请参见[MOT检查点概念](3-6.md#mot检查点概念)。 +- **恢复**:启动时,MogDB首先调用MOT回调,通过加载到内存行并创建索引来恢复MOT检查点,然后根据检查点的LSN重放记录来执行WAL恢复。MOT检查点使用多线程并行恢复,每个线程读取不同的数据段。这使MOT检查点在多核硬件上的恢复速度相当快,尽管可能比仅重放WAL记录的基于磁盘的表慢一些。具体请参见[MOT恢复概念](3-7.md)。 + +
+ +## VACUUM和DROP + +为了最大化MOT功能,我们增加了对VACUUM、DROP TABLE和DROP INDEX的支持。这三个操作都使用排他表锁执行,这意味着不允许在表上并发事务。系统VACUUM调用一个新的FDW函数执行MOT真空,而ValidateTableDef()函数中增加了DROP。 + +
+ +## 删除内存池 + +每个索引和表都跟踪它使用的所有内存池。DROP INDEX命令用于删除元数据。内存池作为单个连续块被删除。MOT VACUUM只对已使用的内存进行压缩,因为内存回收由基于epoch的垃圾收集器(GC)在后台持续进行。为了执行压缩,我们将索引或表切换到新的内存池,遍历所有实时数据,删除每行并使用新池插入数据,最后删除池,就像执行DROP那样。 + +
+ +## 查询本机编译(JIT) + +MOT引擎的FDW适配器还包含一个轻量级执行路径,该路径使用LLVM编译器执行JIT编译查询。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-4.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-4.md new file mode 100644 index 00000000..3c6a0fd9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-4.md @@ -0,0 +1,22 @@ +--- +title: NUMA-aware分配和亲和性 +summary: NUMA-aware分配和亲和性 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# NUMA-aware分配和亲和性 + +非统一内存访问(NUMA)是一种计算机内存设计,用于多重处理,其中内存访问时间取决于内存相对于处理器的位置。处理器可以利用NUMA的优势,优先访问本地内存(速度更快),而不是访问非本地内存(这意味着它不会访问另一个处理器的本地内存或处理器之间共享的内存)。 + +MOT内存访问设计时采用了NUMA感知。即MOT意识到内存不是统一的,而是通过访问最快和最本地的内存来获得最佳性能。 + +NUMA的优点仅限于某些类型的工作负载,特别是数据通常与某些任务或用户强相关的服务器上的工作负载。 + +在NUMA平台上运行的内储存数据库系统面临一些问题,例如访问远程主内存时,时延增加和带宽降低。为了应对这些NUMA相关问题,NUMA感知必须被看作是数据库系统基本架构的主要设计原则。 + +为了便于快速操作和高效利用NUMA节点,MOT为每个表的行分配一个指定的内存池,同时为索引的节点分配一个指定的内存池。每个内存池由多个2MB的块组成。指定API从本地NUMA节点、来自所有节点的页面或通过轮询分配这些块,每个块在下一个节点上分配。默认情况下,共享数据池以轮询方式分配,以保持访问均衡,同时避免在不同NUMA节点之间拆分行。但是,线程专用内存是从一个本地节点分配的,必须验证线程始终运行在同一个NUMA节点中。 + +**总结** + +MOT有一个智能内存控制模块,它预先为各种类型的内存对象分配了内存池。这种智能内存控制可以提高性能,减少锁并保证稳定性。事务的内存对象分配始终是NUMA-local,从而保证了CPU内存访问的最佳性能,降低时延和争用。被释放的对象返回到内存池中。在事务期间最小化使用操作系统的malloc函数可以避免不必要的锁。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-5.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-5.md new file mode 100644 index 00000000..8fabf902 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-5.md @@ -0,0 +1,43 @@ +--- +title: MOT索引 +summary: MOT索引 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT索引 + +MOT索引基于最先进的Masstree的免锁索引,用于多核系统的快速和可扩展的键值(KV)存储,通过B+树的Trie实现。在多核服务器和高并发工作负载上,性能优异。它使用各种先进的技术,如乐观锁方法、缓存感知和内存预取。 + +在比较了各种最先进的解决方案之后,我们选择了Masstree作为索引,因为它显示了点查询、迭代和修改的最佳总体性能。Masstree是Trie和B+树的组合,用以谨慎利用缓存、预取、乐观导航和细粒度锁定。它针对高争用进行了优化,并对其前代产品增加了许多优化,如OLFIT。然而,Masstree索引的缺点是它的内存消耗更高。虽然行数据占用相同的内存大小,但每个索引(主索引或辅助索引)的每行内存平均高了16字节-基于磁盘的表使用基于锁的B树,大小为29字节,而MOT的Masstree大小为45字节。 + +我们的实证研究表明,成熟的免锁Masstree实现与我们对Silo的强大改进相结合,恰能为我们解决这一方面的问题。 + +另一个挑战是对具有多个索引的表使用乐观插入。 + +Masstree索引是用于数据和索引管理的MOT内存布局的核心。我们的团队增强并显著改进了Masstree,同时提交了一些关键贡献给Masstree开源。这些改进包括: + +- 每个索引都有专用内存池:高效分配和快速索引下移 +- Masstree全球GC:快速按需内存回收 +- 具有插入键访问的大众树迭代器实现 +- ARM架构支持 + +我们为Masstree开放源码实现贡献了我们的Masstree索引改进,可以在[https://github.com/kohler/masstree-beta](https://github.com/kohler/masstree-beta)找到。 + +MOT的主要创新是增强了原有的Masstree数据结构和算法,它不支持非唯一索引(作为二级索引)。设计细节请参见[非唯一索引](#非唯一索引)。 + +MOT支持主索引、辅助索引和无键索引(受[不支持的索引DDL和索引](../../../administrator-guide/mot-engine/2-using-mot/4-mot-usage.md#不支持的索引ddl和索引)中提到的限制)。 + +
+ +## 非唯一索引 + +一个非唯一索引可以包含多个具有相同键的行。非唯一索引仅用于通过维护频繁使用的数据值的排序来提高查询性能。例如,数据库可能使用非唯一索引对来自同一家庭的所有人员进行分组。但是,Masstree数据结构实现不允许将多个对象映射到同一个键。我们用于创建非唯一索引的解决方案(如下图所示)是为映射行的键添加一个打破对称的后缀。这个添加的后缀是指向行本身的指针,该行具有8个字节的常量大小,并且值对该行是唯一的。当插入到非唯一索引时,哨兵的插入总是成功的,这使执行事务分配的行能够被使用。这种方法还使MOT能够为非唯一索引提供一个快速、可靠、基于顺序的迭代器。 + +**图 1** 非唯一索引 + +![非唯一索引](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-indexes-1.png) + +上图描述了一个MOT的T表的结构,它有三个行和两个索引。矩形表示数据行,索引指向指向行的哨兵(椭圆形)。哨兵用键插入唯一索引,用键+后缀插入非唯一索引。哨兵可以方便维护操作,无需接触索引数据结构就可替换行。此外,在哨兵中嵌入了各种标志和参考计数,以便于乐观插入。 + +查找非唯一辅助索引时,会使用所需的键(如姓氏)。全串联键只用于插入和删除操作。插入和删除操作总是将行作为参数获取,从而可以创建整个键,并在执行删除或插入索引的特定行时使用它。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-6.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-6.md new file mode 100644 index 00000000..8616c7b3 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-6.md @@ -0,0 +1,208 @@ +--- +title: MOT持久性概念 +summary: MOT持久性概念 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT持久性概念 + +持久性是指长期的数据保护(也称为磁盘持久性)。持久性意味着存储的数据不会遭受任何形式的退化或破坏,因此数据不会丢失或损坏。持久性可确保在有计划停机(例如维护)或计划外崩溃(例如电源故障)后数据和MOT引擎恢复到一致状态。 + +内存存储是易失的,需要电源来维护所存储的信息。另一方面,磁盘存储是非易失性的,这意味着它不需要电源来维护存储的信息,因此它不用担心停电。MOT使用这两种类型的存储,它拥有内存中的所有数据,同时将事务性更改持久化到磁盘,并保持频繁的定期**MOT检查点**,以确保在关机时恢复数据。 + +用户必须保证有足够的磁盘空间用于日志记录和检查点操作。检查点使用单独的驱动器,通过减少磁盘I/O负载来提高性能。 + +有关如何在MOT引擎中实现持久性的概述,请参见[MOT关键技术](../../../administrator-guide/mot-engine/1-introducing-mot/3-mot-key-technologies.md)。 + +MOT的WAL重做日志和检查点启用了持久性,如下所述。 + +- [MOT日志记录:WAL重做日志概念](#mot日志记录wal重做日志概念) +- [MOT检查点概念](#mot检查点概念) + +
+ +## MOT日志记录:WAL重做日志概念 + +### 概述 + +预写日志记录(WAL)是确保数据持久性的标准方法。WAL的主要概念是,数据文件(表和索引所在的位置)的更改只有在记录这些更改之后才会写入,即只有在描述这些更改的日志记录被刷新到永久存储之后才会写入。 + +MOT全面集成MogDB的封装日志记录设施。除持久性外,这种方法的另一个好处是能够将WAL用于复制目的。 + +支持三种日志记录方式:两种标准同步和一种异步方式。标准MogDB磁盘引擎也支持这三种日志记录方式。此外,在MOT中,组提交(Group-Commit)选项还提供了特殊的NUMA感知优化。Group-Commit在维护ACID属性的同时提供最高性能。 + +为保证持久性,MOT全面集成MogDB的WAL机制,通过MogDB的XLOG接口持久化WAL记录。这意味着,每次MOT记录的添加、更新和删除都记录在WAL中。这确保了可以从这个非易失性日志中重新生成和恢复最新的数据状态。例如,如果向表中添加了3个新行,删除了2个,更新了1个,那么日志中将记录6个条目。 + +- MOT日志记录和MogDB磁盘表的其他记录写入同一个WAL中。 +- MOT只记录事务提交阶段的操作。 +- MOT只记录更新的增量记录,以便最小化写入磁盘的数据量。 +- 在恢复期间,从最后一个已知或特定检查点加载数据;然后使用WAL重做日志完成从该点开始发生的数据更改。 +- WAL重做日志将保留所有表行修改,直到执行一个检查点为止(如上所述)。然后可以截断日志,以减少恢复时间和节省磁盘空间。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 为了确保日志IO设备不会成为瓶颈,日志文件必须放在具有低时延的驱动器上。 + +
+ +### 日志类型 + +支持两个同步事务日志选项和一个异步事务日志选项(标准MogDB磁盘引擎也支持这些选项)。MOT还支持同步的组提交日志记录与NUMA感知优化,如下所述。 + +根据您的配置,实现以下类型的日志记录: + +- **同步重做日志记录** + + 同步重做日志记录选项是最简单、最严格的重做日志记录器。当客户端应用程序提交事务时,事务重做条目记录在WAL重做日志中,如下所示: + + 1. 当事务正在进行时,它存储在MOT内存中。 + 2. 事务完成后,客户端应用程序发送提交命令,该事务被锁定,然后写入磁盘上的WAL重做日志。这意味着,当事务日志条目写入日志时,客户端应用程序仍在等待响应。 + 3. 一旦事务的整个缓冲区被写入日志,就更改内存中的数据,然后提交事务。事务提交后,客户端应用程序收到事务完成通知。 + + **技术说明** + + 当事务结束时,同步重做日志处理程序(SynchronousRedoLogHandler)序列化事务缓冲区,并写入XLOG iLogger实现。 + + **图 1** 同步日志记录 + + ![同步日志记录](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-durability-concepts-1.png) + + **总结** + + **同步重做日志记录**选项是最安全、最严格的,因为它确保了客户端应用程序和每个事务提交时的WAL重做日志条目的完全同步,从而确保了总的持久性和一致性,并且绝对不会丢失数据。此日志记录选项可防止客户端应用程序在事务尚未持久化到磁盘时将事务标记为成功的情况。 + + 同步重做日志记录选项的缺点是,它是三个选项中最慢的日志机制。这是因为客户端应用程序必须等到所有数据都写入磁盘,并且磁盘频繁写入(这通常使数据库变慢)。 + +- **组同步重做日志记录** + + **组同步重做日志记录**选项与**同步重做日志记录**选项非常相似,因为它还确保完全持久性,绝对不会丢失数据,并保证客户端应用程序和WAL重做日志条目的完全同步。不同的是,**组同步重做日志记录**选项将事务重做条目组同时写入磁盘上的WAL重做日志,而不是在提交时写入每个事务。使用组同步重做日志记录可以减少磁盘I/O数量,从而提高性能,特别是在运行繁重的工作负载时。 + + MOT引擎通过根据运行事务的核的NUMA槽位自动对事务进行分组,使用非统一内存访问(NUMA)感知优化来执行同步的组提交记录。 + + 有关NUMA感知内存访问的更多信息,请参见[NUMA-aware分配和亲和性](3-4.md)。 + + 当一个事务提交时,一组条目记录在WAL重做日志中,如下所示: + + 1. 当事务正在进行时,它存储在内存中。MOT引擎根据运行事务的核的NUMA槽位对桶中的事务进行分组。这意味着在同一槽位上运行的所有事务都被分在一组,并且多个组将根据事务运行的核心并行填充。 + + 这样,将事务写入WAL更为有效,因为来自同一个槽位的所有缓冲区都一起写入磁盘。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: - 每个线程在属于单个槽位的单核/CPU上运行,每个线程只写运行于其上的核的槽位。 + + 2. 在事务完成并且客户端应用程序发送Commit命令之后,事务重做日志条目将与属于同一组的其他事务一起序列化。 + + 3. 当特定一组事务满足配置条件后,如《重做日志(MOT)》小节中描述的已提交的事务数或超时时间,该组中的事务将被写入磁盘的WAL中。这意味着,当这些日志条目被写入日志时,发出提交请求的客户端应用程序正在等待响应。 + + 4. 一旦NUMA-aware组中的所有事务缓冲区都写入日志,该组中的所有事务都将对内存存储执行必要的更改,并且通知客户端这些事务已完成。 + + **技术说明** + + 4种颜色分别代表4个NUMA节点。因此,每个NUMA节点都有自己的内存日志,允许多个连接的组提交。 + + **图 2** 组提交-具有NUMA感知 + + ![组提交-具有NUMA感知](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-durability-concepts-2.png) + + **总结** + + 组同步重做日志记录选项是一个极其安全和严格的日志记录选项,因为它保证了客户端应用程序和WAL重做日志条目的完全同步,从而确保总的持久性和一致性,并且绝不会丢失数据。此日志记录选项可防止客户端应用程序在事务尚未持久化到磁盘时将事务标记为成功的情况。 + + 一方面,该选项的磁盘写入次数比同步重做日志记录选项少,这可能意味着它更快。缺点是事务被锁定的时间更长,这意味着它们被锁定,直到同一NUMA内存中的所有事务都写入磁盘上的WAL重做日志为止。 + + 使用此选项的好处取决于事务工作负载的类型。例如,此选项有利于事务多的系统(而对于事务少的系统而言,则较少使用,因为磁盘写入量也很少)。 + +- **异步重做日志记录** + + **异步重做日志记录**选项是最快的日志记录方法,但是,它不能确保数据不会丢失。也就是说,某些仍位于缓冲区且尚未写入磁盘的数据在电源故障或数据库崩溃时可能会丢失。当客户端应用程序提交事务时,事务重做条目将记录在内部缓冲区中,并按预先配置的时间间隔写入磁盘。客户端应用程序不会等待数据写入磁盘,而是继续到下一个事务。因此异步重做日志记录的速度最快。 + + 当客户端应用程序提交事务时,事务重做条目记录在WAL重做日志中,如下所示: + + 1. 当事务正在进行时,它存储在MOT内存中。 + 2. 在事务完成并且客户端应用程序发送Commit命令后,事务重做条目将被写入内部缓冲区,但尚未写入磁盘。然后更改MOT数据内存,并通知客户端应用程序事务已提交。 + 3. 后台运行的重做日志线程按预先配置的时间间隔收集所有缓存的重做日志条目,并将它们写入磁盘。 + + **技术说明** + + 在事务提交时,事务缓冲区被移到集中缓冲区(指针分配,而不是数据副本),并为事务分配一个新的事务缓冲区。一旦事务缓冲区移动到集中缓冲区,且事务线程不被阻塞,事务就会被释放。实际写入日志使用Postgres WALWRITER线程。当WALWRITER计时器到期时,它首先调用异步重做日志处理程序(通过注册的回调)来写缓冲区,然后继续其逻辑,并将数据刷新到XLOG中。 + + **图 3** 异步日志记录 + + ![异步日志记录](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-durability-concepts-3.png) + + **总结** + + 异步重做日志记录选项是最快的日志记录选项,因为它不需要客户端应用程序等待数据写入磁盘。此外,它将许多事务重做条目分组并把它们写入一起,从而减少降低MOT引擎速度的磁盘I/O数量。 + + 异步重做日志记录选项的缺点是它不能确保在崩溃或失败时数据不会丢失。已提交但尚未写入磁盘的数据在提交时是不持久的,因此在出现故障时无法恢复。异步重做日志记录选项对于愿意牺牲数据恢复(一致性)而不是性能的应用程序来说最为相关。 + + 日志记录设计细节 + + 下面将详细介绍内储存引擎模块中与持久化相关的各个组件的设计细节。 + + **图 4** 三种日志记录选项 + + ![三种日志记录选项](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-durability-concepts-4.png) + +重做日志组件由使用内储存引擎的后端线程和WAL编写器使用,以便持久化其数据。检查点通过Checkpoint管理器执行,由Postgres的Checkpointer触发。 + +- **日志记录设计概述** + + 预写日志记录(WAL)是确保数据持久性的标准方法。WAL的核心概念是,数据文件(表和索引所在的位置)的更改只有在记录了这些更改之后才会写入,这意味着在描述这些更改的日志记录被刷新到永久存储之后。 + + 在内储存引擎中,我们使用现有的MogDB日志设施,并没有从头开始开发低级别的日志API,以减少开发时间并使其可用于复制目的。 + +- **单事务日志记录** + + 在内储存引擎中,事务日志记录存储在事务缓冲区中,事务缓冲区是事务对象(TXN)的一部分。在调用addToLog()时记录事务缓冲区-如果缓冲区超过阈值,则将其刷新并重新使用。当事务提交并通过验证阶段或由于某种原因中止时,相应的消息也会保存在日志中,以便能够在恢复期间确定事务的状态。 + +**图 5** 单事务日志记录 + +![单事务日志记录](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/mot-durability-concepts-5.png) + +并行日志记录由MOT和磁盘引擎执行。但是,MOT引擎通过每个事务的日志缓冲区、无锁准备和单个日志记录增强了这种设计。 + +- **异常处理** + + 持久化模块通过Postgres错误报告基础设施(ereport)处理异常。系统日志中会记录每个错误情况的错误信息。此外,使用Postgres内置的错误报告基础设施将错误报告到封装。 + + 该模块上报有如下异常: + +**表 1** 异常处理 + +| 异常条件 | 异常码 | 场景描述 | 最终结果 | +| :----------------------- | :----------------------------- | :------------------------------------- | :------------- | +| WAL写入失败 | ERRCODE_FDW_ERROR | 在任何情况下,WAL写入失败 | 事务终止 | +| 文件IO错误:写入、打开等 | ERRCODE_IO_ERROR | 检查点:在任何文件访问错误时调用 | 严重:进程存在 | +| 内存不足 | ERRCODE_INSUFFICIENT_RESOURCES | 检查点:本地内存分配失败 | 严重:进程存在 | +| 逻辑、DB错误 | ERRCODE*INTERNAL*错误 | 检查点:算法失败或无法检索表数据或索引 | 严重:进程存在 | + +
+ +## MOT检查点概念 + +在MogDB中,检查点是事务序列中一个点的快照,在该点上,可以保证堆和索引数据文件已经同步了检查点之前写入的所有信息。 + +在执行检查点时,所有脏数据页都会刷新到磁盘,并将一个特殊的检查点记录写入日志文件。 + +数据直接存储在内存中。MOT没有像MogDB那样存储数据,因此不存在脏页的概念。 + +为此,我们研究并实现了CALC算法,该算法在耶鲁大学发布的Low-Overhead Asynchronous Checkpointing in Main-Memory Database Systems, SIGMOND 2016中得到了描述。 + +主内存数据库系统中的低开销异步检查点。 + +
+ +### CALC检查点算法:内存和计算开销低 + +检查点算法具有以下优点: + +- 降低内存使用量-每条记录在任何时候最多存储两个副本。在记录处于活动且稳定版本相同或没有记录任何检查点时,仅存储记录的一个物理副本,可以最大限度地减少内存使用。 +- **低开销**:CALC的开销比其他异步检查点算法小。 +- **使用虚拟一致性点**:CALC不需要静默数据库以实现物理一致性点。 + +
+ +### 检查点激活 + +MOT检查点被集成到MogDB的封装的检查点机制中。检查点流程可以通过执行**CHECKPOINT**;命令手动触发,也可以根据封装的检查点触发设置(时间/大小)自动触发。 + +检查点配置在mot.conf文件中执行,请参见[检查点(MOT)](../../../administrator-guide/mot-engine/2-using-mot/3-mot-deployment.md#检查点mot)部分。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-7.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-7.md new file mode 100644 index 00000000..e445a17b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-7.md @@ -0,0 +1,24 @@ +--- +title: MOT恢复概念 +summary: MOT恢复概念 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT恢复概念 + +MOT恢复模块提供了恢复MOT表数据所需的所有功能。恢复模块的主要目标是在计划(例如维护)关闭或计划外(例如电源故障)崩溃后,将数据和MOT引擎恢复到一致的状态。 + +MogDB数据库恢复(有时也称为冷启动)包括MOT表,并且随着数据库其余部分的恢复而自动执行。MOT恢复模块无缝、全面地集成到MogDB恢复过程中。 + +MOT恢复有两个主要阶段:检查点恢复和WAL恢复(重做日志)。 + +MOT检查点恢复在封装的恢复发生之前执行。仅在冷启动事件(PG进程的启动)中执行此操作。它首先恢复元数据,然后插入当前有效检查点的所有行,这由checkpoint_recovery_workers并行完成,每个行都在不同的表中工作。索引在插入过程中创建。 + +在检查点时,表被分成多个16MB的块,以便多个恢复工作进程可以并行地恢复表。这样做是为了加快检查点恢复速度,它被实现为一个多线程过程,其中每个线程负责恢复不同的段。不同段之间没有依赖关系,因此线程之间没有争用,在更新表或插入新行时也不需要使用锁。 + +WAL记录作为封装的WAL恢复的一部分进行恢复。MogDB封装会迭代XLOG,根据xlog记录类型执行必要的操作。如果是记录类型为MOT的条目,封装将它转发给MOT 恢复管理器进行处理。如果XLOG条目太旧(即XLOG条目的LSN比检查点的LSN旧),MOT恢复将忽略该条目。 + +在主备部署中,备用服务器始终处于Recovery状态,以便自动WAL恢复过程。 + +MOT恢复参数在mot.conf文件中配置,参见[MOT恢复](../../../administrator-guide/mot-engine/2-using-mot/5-mot-administration.md#mot恢复)。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-8.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-8.md new file mode 100644 index 00000000..0e7e8a28 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-8.md @@ -0,0 +1,79 @@ +--- +title: MOT查询原生编译(JIT) +summary: MOT查询原生编译(JIT) +author: Zhang Cuiping +date: 2021-03-04 +--- + +# MOT查询原生编译(JIT) + +MOT使您可以在执行之前以原生格式(使用PREPARE语句)准备并分析预编译的完整查询。 + +这种本机格式以后可以更有效地执行(使用EXECUTE命令)。这种类型的执行效率要高得多,因为在执行期间,本机格式绕过了多个数据库处理层。这种分工避免了重复的解析分析操作。Lite Executor模块负责执行预准备查询,其执行路径比封装执行的常规通用计划要快得多。这是通过LLVM使用实时(JIT)编译来实现的。此外,以伪LLVM的形式提供具有潜在相似性能的类似解决方案。 + +下面是SQL中的PREPARE语法示例: + +``` +PREPARE name [ ( data_type [, ...] ) ] AS statement +``` + +下面是一个如何在Java应用程序中调用PREPARE和EXECUTE语句的示例: + +```java +conn = DriverManager.getConnection(connectionUrl, connectionUser, connectionPassword); + +// Example 1: PREPARE without bind settings +String query = "SELECT * FROM getusers"; +PreparedStatement prepStmt1 = conn.prepareStatement(query); +ResultSet rs1 = pstatement.executeQuery()) +while (rs1.next()) {…} + +// Example 2: PREPARE with bind settings +String sqlStmt = "SELECT * FROM employees where first_name=? and last_name like ?"; +PreparedStatement prepStmt2 = conn.prepareStatement(sqlStmt); +prepStmt2.setString(1, "Mark"); // first name “Mark” +prepStmt2.setString(2, "%n%"); // last name contains a letter “n” +ResultSet rs2 = prepStmt2.executeQuery()) +while (rs2.next()) {…} +``` + +
+ +## Prepare + +**Prepare**创建一个预处理语句。预处理语句是服务器端对象,可用于优化性能。执行PREPARE语句时,将解析、分析和重写指定的语句。 + +如果查询语句中提到的表是MOT表,则MOT编译负责对象准备,并基于LLVM将查询编译成IR字节码进行特殊优化。 + +每当需要新的查询编译时,都会分析查询,并使用实用程序GsCodeGen对象和标准LLVM JIT API (IRBuilder)为查询生成合适的IR字节代码。完成字节代码生成后,代码将被JIT编译到单独的LLVM模块中。编译的代码生成一个C函数指针,以后可以调用该指针直接执行。请注意,这个C函数可以被许多线程并发调用,只要每个线程提供不同的执行上下文(详细信息如下)。每个这样的执行上下文称为“JIT上下文”。 + +为了进一步提高性能,MOT JIT对其LLVM代码结果应用缓存策略,使它们能够被在不同会话中的相同查询重用。 + +
+ +## 执行 + +当发出EXECUTE命令时,会计划并执行预准备语句(上文所述)。这种分工避免了重复的解析分析工作,同时使执行计划依赖于提供的特定设置值。 + +当生成的执行查询命令到达数据库时,它使用相应的IR字节代码,在MOT引擎中直接执行该代码,并且执行效率更高。这称为“轻量级执行”。 + +此外,为了可用性,Lite Executor维护了一个预先分配的JIT源池。每个会话预分配自己的会话本地JIT上下文对象池(用于重复执行预编译查询)。 + +有关更多详细信息,请参阅“支持Lite执行的查询”和“不支持Lite执行的查询”部分。 + +
+ +## JIT编译对比-MogDB盘表与MOT表 + +目前,MogDB包含针对其基于磁盘的表的JIT/CodeGen查询优化的两种主要形式: + +- 加速表达式计算,例如在WHERE子句、目标列表、聚合和投影中。 +- 内联小函数调用。 + +这些优化是局部的(从某种意义上说,它们不优化整个解释的运算符树或完全替换它),并且主要针对CPU绑定的复杂查询,通常在OLAP用例中可见。查询的执行是在使用解释运算符树的拉模型(Volcano样式处理)中执行的。激活后,每次执行查询时都会执行编译。目前,尚未提供生成的LLVM代码的缓存及其跨会话和查询的重用。 + +相反,MOT JIT优化为符合MOT JIT优化条件的整个查询提供了LLVM代码。结果代码用于直接执行MOT表,而解释的运算符模型则完全放弃。结果实际上是为整个特定查询执行生成的手写LLVM代码。 + +另一个显着的概念差异是MOT LLVM代码只在查询的PREPARE阶段为准备查询生成,而不是在查询执行时生成。由于OLTP查询的运行时间相当短,因此这对于OLTP场景尤其重要,这无法在每次查询执行期间生成代码和执行较长的查询编译时间。 + +最后,在PostgreSQL中,激活PREPARE意味着于同一个会话中具有不同参数的执行之间重用生成的计划。同样,MOT JIT对其LLVM代码结果应用了缓存策略,并扩展了缓存策略,以便在不同会话之间重用。因此,单个查询可以只编译一次,其LLVM代码可以在多个会话中重用,这同样有利于OLTP场景。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-9.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-9.md new file mode 100644 index 00000000..4d0079e2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/3-concepts-of-mot/3-9.md @@ -0,0 +1,33 @@ +--- +title: 对比:磁盘与MOT +summary: 对比:磁盘与MOT +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 对比:磁盘与MOT + +下表简要对比了基于MogDB磁盘的存储引擎和MOT存储引擎的各种特性。 + +对比:基于磁盘与MOT + +| 特性 | MogDB 磁盘存储 | MogDB MOT引擎 | +| :--------------------- | :-------------- | :---------------------- | +| 英特尔x86+鲲鹏ARM | 是 | 是 | +| SQL和功能集覆盖率 | 100% | 98% | +| 纵向扩容(多核,NUMA) | 低效 | 高效 | +| 吞吐量 | 高 | 极高 | +| 时延 | 低 | 极低 | +| 分布式 | 是 | 是 | +| 隔离级别 | RC+SIRR序列化 | RCRRRC+SI(V2版本) | +| 并发控制策略 | 悲观 | 乐观 | +| 数据容量(数据+索引) | 不受限制 | 受限于DRAM | +| 本地编译 | 否 | 是 | +| 复制、恢复 | 是 | 是 | +| 复制选项 | 2(同步,异步) | 3(同步、异步、组提交) | + +**其中,** + +- RR=可重复读取 +- RC=读已提交 +- SI=快照隔离 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/4-appendix/1-references.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/4-appendix/1-references.md new file mode 100644 index 00000000..0c6dcc03 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/4-appendix/1-references.md @@ -0,0 +1,40 @@ +--- +title: 参考文献 +summary: 参考文献 +author: Zhang Cuiping +date: 2021-05-18 +--- + +# 参考文献 + +[1] Y. Mao, E. Kohler, and R. T. Morris. Cache craftiness for fast multicore key-value storage. In Proc. 7th ACM European Conference on Computer Systems (EuroSys), Apr. 2012. + +[2] K. Ren, T. Diamond, D. J. Abadi, and A. Thomson. Low-overhead asynchronous checkpointing in main-memory database systems. In Proceedings of the 2016 ACM SIGMOD International Conference on Management of Data, 2016. + +[3] + +[4] + +[5] Tu, S., Zheng, W., Kohler, E., Liskov, B., and Madden, S. Speedy transactions in multicore in-memory databases. In Proceedings of the Twenty-Fourth ACM Symposium on Operating Systems Principles (New York, NY, USA, 2013), SOSP ’13, ACM, pp. 18-32. + +[6] H. Avni at al. Industrial-Strength OLTP Using Main Memory and Many-cores, VLDB 2020. + +[7] Bernstein, P. A., and Goodman, N. Concurrency control in distributed database systems. ACM Comput. Surv. 13, 2 (1981), 185-221. + +[8] Felber, P., Fetzer, C., and Riegel, T. Dynamic performance tuning of word-based software transactional memory. In Proceedings of the 13th ACM SIGPLAN Symposium on Principles and Practice of Parallel Programming, PPOPP 2008, Salt Lake City, UT, USA, February 20-23, 2008 (2008), + +pp. 237-246. + +[9] Appuswamy, R., Anadiotis, A., Porobic, D., Iman, M., and Ailamaki, A. Analyzing the impact of system architecture on the scalability of OLTP engines for high-contention workloads. PVLDB 11, 2 (2017), + +121-134. + +[10] R. Sherkat, C. Florendo, M. Andrei, R. Blanco, A. Dragusanu, A. Pathak, P. Khadilkar, N. Kulkarni, C. Lemke, S. Seifert, S. Iyer, S. Gottapu, R. Schulze, C. Gottipati, N. Basak, Y. Wang, V. Kandiyanallur, S. Pendap, D. Gala, R. Almeida, and P. Ghosh. Native store extension for SAP HANA. PVLDB, 12(12): + +2047-2058, 2019. + +[11] X. Yu, A. Pavlo, D. Sanchez, and S. Devadas. Tictoc: Time traveling optimistic concurrency control. In Proceedings of the 2016 International Conference on Management of Data, SIGMOD Conference 2016, San Francisco, CA, USA, June 26 - July 01, 2016, pages 1629-1642, 2016. + +[12] V. Leis, A. Kemper, and T. Neumann. The adaptive radix tree: Artful indexing for main-memory databases. In C. S. Jensen, C. M. Jermaine, and X. Zhou, editors, 29th IEEE International Conference on Data Engineering, ICDE 2013, Brisbane, Australia, April 8-12, 2013, pages 38-49. IEEE Computer Society, 2013. + +[13] S. K. Cha, S. Hwang, K. Kim, and K. Kwon. Cache-conscious concurrency control of main-memory indexes on shared-memory multiprocessor systems. In P. M. G. Apers, P. Atzeni, S. Ceri, S. Paraboschi, K. Ramamohanarao, and R. T. Snodgrass, editors, VLDB 2001, Proceedings of 27th International Conference on Very Large Data Bases, September 11-14, 2001, Roma, Italy, pages 181-190. Morga Kaufmann, 2001. diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/4-appendix/2-glossary.md b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/4-appendix/2-glossary.md new file mode 100644 index 00000000..ff47d4ff --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/mot-engine/4-appendix/2-glossary.md @@ -0,0 +1,59 @@ +--- +title: 术语表 +summary: 术语表 +author: Zhang Cuiping +date: 2021-05-18 +--- + +# 术语表 + +| 缩略语 | 定义描述 | +| :----- | :----------------------------------------------------------- | +| 2PL | 2阶段锁(2-Phase Locking) | +| ACID | 原子性(Atomicity),一致性(Consistency),隔离性(Isolation),持久性(Durability) | +| AP | 分析处理(Analytical Processing) | +| Arm | 高级RISC机器(Advanced RISC Machine),x86的替代硬件架构。 | +| CC | 并发控制(Concurrency Control) | +| CPU | 中央处理器(Central Processing Unit) | +| DB | 数据库(Database) | +| DBA | 数据库管理员(Database Administrator) | +| DBMS | 数据库管理系统(DataBase Management System) | +| DDL | 数据定义语言(Data Definition Language)数据库模式管理语言 | +| DML | 数据修改语言(Data Modification Language) | +| ETL | 提取、转换、加载或遇时锁定(Extract, Transform, Load or Encounter Time Locking) | +| FDW | 外部数据封装(Foreign Data Wrapper) | +| GC | 垃圾收集器(Garbage Collector) | +| HA | 高可用性(High Availability) | +| HTAP | 事务分析混合处理(Hybrid Transactional-Analytical Processing) | +| IoT | 物联网(Internet of Things) | +| IM | 内储存(In-Memory) | +| IMDB | 内储存数据库(In-Memory Database) | +| IR | 源代码的中间表示(Intermediate Representation),用于编译和优化 | +| JIT | 准时(Just In Time) | +| JSON | JavaScript对象表示法(JavaScript Object Notation) | +| KV | 键值(Key Value) | +| LLVM | 低级虚拟机(Low-Level Virtual Machine),指编译代码或IR查询 | +| M2M | 机对机(Machine-to-Machine) | +| ML | 机器学习(Machine Learning) | +| MM | 主内存(Main Memory) | +| MO | 内存优化(Memory Optimized) | +| MOT | 内存优化表存储引擎(SE),读作/em/ /oh/ /tee/ | +| MVCC | 多版本并发控制(Multi-Version Concurrency Control) | +| NUMA | 非一致性内存访问(Non-Uniform Memory Access) | +| OCC | 乐观并发控制(Optimistic Concurrency Control) | +| OLTP | 在线事务处理(On-Line Transaction Processing),多用户在线交易类业务 | +| PG | PostgreSQL | +| RAW | 写后读校验(Reads-After-Writes) | +| RC | 返回码(Return Code) | +| RTO | 目标恢复时间(Recovery Time Objective) | +| SE | 存储引擎(Storage Engine) | +| SQL | 结构化查询语言(Structured Query Language) | +| TCO | 总体拥有成本(Total Cost of Ownership) | +| TP | 事务处理(Transactional Processing) | +| TPC-C | 一种联机事务处理基准 | +| Tpm-C | 每分钟事务数-C. TPC-C基准的性能指标,用于统计新订单事务。 | +| TVM | 微小虚拟机(Tiny Virtual Machine) | +| TSO | 分时选项(Time Sharing Option) | +| UDT | 自定义类型 | +| WAL | 预写日志(Write Ahead Log) | +| XLOG | 事务日志的PostgreSQL实现(WAL,如上文所述) | diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/primary-and-standby-management.md b/product/zh/docs-mogdb/v3.1/administrator-guide/primary-and-standby-management.md new file mode 100644 index 00000000..6a56dd21 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/primary-and-standby-management.md @@ -0,0 +1,134 @@ +--- +title: 主备管理 +summary: 主备管理 +author: Guo Huan +date: 2021-03-11 +--- + +# 主备管理 + +## 操作场景 + +MogDB在运行过程中,数据库管理员可能需要手工对数据库节点做主备切换。例如发现数据库节点主备failover后需要恢复原有的主备角色,或怀疑硬件故障需要手动进行主备切换。级联备机不能直接转换为主机,只能先通过switchover或者failover成为备机,然后再切换为主机。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** +> +> - 主备切换为维护操作,确保MogDB状态正常,所有业务结束后,再进行切换操作。 +> - 在开启极致RTO时,不支持级联备机。级联备机因为极致RTO开启情况下,备机不支持连接无法同步数据。 + +
+ +## 操作步骤 + +1. 以操作系统用户omm登录数据库任意节点,执行如下命令,查看主备情况。 + + ```bash + gs_om -t status --detail + ``` + +2. 以操作系统用户omm登录准备切换为主节点的备节点,执行如下命令。 + + ```bash + gs_ctl switchover -D /home/omm/cluster/dn1/ + ``` + + /home/omm/cluster/dn1/为备数据库节点的数据目录。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知:** 对于同一数据库,上一次主备切换未完成,不能执行下一次切换。对于业务正在操作时,发起switchover,可能主机的线程无法停止导致switchover显示超时,实际后台仍然在运行,等主机线程停止后,switchover即可完成。比如在主机删除一个大的分区表时,可能无法响应switchover发起的信号。 + +3. switchover成功后,执行如下命令记录当前主备机器信息。 + + ```bash + gs_om -t refreshconf + ``` + +
+ +## 示例 + +将数据库节点备实例切换为主实例。 + +1. 查询数据库状态。 + + ```bash + gs_om -t status --detail + [ Cluster State ] + + cluster_state : Normal + redistributing : No + current_az : AZ_ALL + + [ Datanode State ] + + node node_ip port instance state + -------------------------------------------------------------------------------------------------- + 1 pekpopgsci00235 10.244.62.204 5432 6001 /home/omm/cluster/dn1/ P Primary Normal + 2 pekpopgsci00238 10.244.61.81 5432 6002 /home/omm/cluster/dn1/ S Standby Normal + ``` + +2. 登录备节点,进行主备切换。另外,switchover级联备机后,级联备机切换为备机,原备机将为级联备。 + + ```bash + gs_ctl switchover -D /home/omm/cluster/dn1/ + [2020-06-17 14:28:01.730][24438][][gs_ctl]: gs_ctl switchover ,datadir is -D "/home/omm/cluster/dn1" + [2020-06-17 14:28:01.730][24438][][gs_ctl]: switchover term (1) + [2020-06-17 14:28:01.768][24438][][gs_ctl]: waiting for server to switchover............ + [2020-06-17 14:28:11.175][24438][][gs_ctl]: done + [2020-06-17 14:28:11.175][24438][][gs_ctl]: switchover completed (/home/omm/cluster/dn1) + ``` + +3. 保存数据库主备机器信息。 + + ```bash + gs_om -t refreshconf + Generating dynamic configuration file for all nodes. + Successfully generated dynamic configuration file. + ``` + +
+ +## 错误排查 + +如果switchover过程中出现失败,请根据日志文件中的日志信息排查错误,参见[日志参考](../administrator-guide/routine-maintenance/11-log-reference.md)。 + +
+ +## 异常处理 + +异常判断标准如下: + +- 业务压力下,主备实例切换时间长,这种情况不需要处理。 + +- 其他备机正在build的情况下,主机需要发送日志到备机后,才能降备,导致主备切换时间长。这种情况不需要处理,但应尽量避免build过程中进行主备切换。 + +- 切换过程中,因网络故障、磁盘满等原因造成主备实例连接断开,出现双主现象时,此时请参考如下步骤修复。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-warning.gif) **警告:** 出现双主状态后,请按如下步骤恢复成正常的主备状态。否则可能会造成数据丢失。 + +1. 执行以下命令查询数据库当前的实例状态。 + + ```bash + gs_om -t status --detail + ``` + + 若查询结果显示两个实例的状态都为Primary,这种状态为异常状态。 + +2. 确定降为备机的节点,在节点上执行如下命令关闭服务。 + + ```bash + gs_ctl stop -D /home/omm/cluster/dn1/ + ``` + +3. 执行以下命令,以standby模式启动备节点。 + + ```bash + gs_ctl start -D /home/omm/cluster/dn1/ -M standby + ``` + +4. 保存数据库主备机器信息。 + + ```bash + gs_om -t refreshconf + ``` + +5. 查看数据库状态,确认实例状态恢复。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/0-starting-and-stopping-mogdb.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/0-starting-and-stopping-mogdb.md new file mode 100644 index 00000000..059d0220 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/0-starting-and-stopping-mogdb.md @@ -0,0 +1,219 @@ +--- +title: 启停MogDB +summary: 启停MogDB +author: Guo Huan +date: 2021-06-24 +--- + +# 启停MogDB + +## OM启停 + +### 启动MogDB + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用以下命令启动MogDB。 + + ```bash + gs_om -t start + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 双机启动必须以双机模式启动,若中间过程以单机模式启动,则必须修复才能恢复双机关系,用gs_ctl build进行修复,gs_ctl的使用方法参见“参考指南 > 工具参考 > 系统内部使用的工具 > [gs_ctl](../../reference-guide/tool-reference/tools-used-in-the-internal-system/4-gs_ctl.md)”章节。 + +### 停止MogDB + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用以下命令停止MogDB。 + + ```bash + gs_om -t stop + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: + > 启停节点及AZ的操作请参见“参考指南 > 工具参考 > 服务端工具 > [gs_om](../../reference-guide/tool-reference/server-tools/8-gs_om.md)”章节。 + +### 示例 + +启动MogDB: + +```bash +gs_om -t start +Starting cluster. +========================================= +========================================= +Successfully started. +``` + +停止MogDB: + +```bash +gs_om -t stop +Stopping cluster. +========================================= +Successfully stopped cluster. +========================================= +End stop cluster. +``` + +### 错误排查 + +如果启动MogDB或者停止MogDB服务失败,请根据日志文件中的日志信息排查错误,参见[日志参考](11-log-reference.md)。 + +如果是超时导致启动失败,可以执行如下命令,设置启动超时时间,默认超时时间为300s。 + +```bash +gs_om -t start --time-out=300 +``` + +
+ +## PTK启停 + +### 启动集群 + +> 下面的集群操作以集群 `cluster_slirist` 为例 + +在安装完数据库集群后,PTK 默认会将数据库集群启动。 + +如果安装时指定了 `--skip-launch-db` 的话,数据库会处于停止状态。 + +此时可通过 `cluster start` 指令启动集群,需指定集群的集群名称。 + +示例: + +```shell +# ptk cluster -n cluster_slirist start +INFO[2022-08-02T11:40:48.728] Operating: Starting. +INFO[2022-08-02T11:40:48.728] ========================================= +INFO[2022-08-02T11:40:48.784] starting host 192.168.122.101 +INFO[2022-08-02T11:40:54.097] starting host 192.168.122.101 successfully +INFO[2022-08-02T11:40:54.097] starting host 192.168.122.102 +INFO[2022-08-02T11:40:56.329] starting host 192.168.122.102 successfully +INFO[2022-08-02T11:40:56.613] waiting for check cluster state... +INFO[2022-08-02T11:41:01.861] ========================================= +INFO[2022-08-02T11:41:01.861] Successfully started. +INFO[2022-08-02T11:41:01.861] Operation succeeded: Start. +``` + +同时,PTK 默认会启动集群内所有实例,PTK 也支持指定单个实例启动: + +```shell +# ptk cluster -n cluster_slirist start -H 192.168.122.101 +INFO[2022-08-02T11:50:04.442] Operating: Starting. +INFO[2022-08-02T11:50:04.442] ========================================= +INFO[2022-08-02T11:50:06.692] starting host 192.168.122.101 successfully +``` + +更多启动参数请查看帮助文档: + +```shell +# ptk cluster start -h +启动数据库实例或集群 + +Usage: + ptk cluster start [flags] + +Flags: + -h, --help help for start + -H, --host string 操作的实例IP + -n, --name string 集群名称 + --security-mode string 是否使用安全模式启动数据库 + 可选项: on/off + --time-out duration 启动超时时间 (default 10m0s) +``` + +### 停止集群 + +> 下面的集群操作以集群 `cluster_slirist` 为例 + +如果想要停止数据库集群,可以通过 `cluster stop` 指令,默认会停止集群内所有实例: + +```shell +# ptk cluster -n cluster_slirist stop +INFO[2022-08-02T11:49:40.685] Operating: Stopping. +INFO[2022-08-02T11:49:40.685] ========================================= +INFO[2022-08-02T11:49:40.891] stopping host 192.168.122.102 +INFO[2022-08-02T11:49:41.946] stopping host 192.168.122.102 successfully +INFO[2022-08-02T11:49:41.946] stopping host 192.168.122.101 +INFO[2022-08-02T11:49:43.004] stopping host 192.168.122.101 successfully +INFO[2022-08-02T11:49:43.004] ========================================= +INFO[2022-08-02T11:49:43.004] Successfully stoped. +INFO[2022-08-02T11:49:43.004] Operation succeeded: Stop. +``` + +如果想要停止集群内某个实例,可通过 `-H` 指定实例的IP + +```shell +# ptk cluster -n cluster_slirist stop -H 192.168.122.101 +INFO[2022-08-02T11:56:32.880] Operating: Stopping. +INFO[2022-08-02T11:56:32.881] ========================================= +INFO[2022-08-02T11:56:34.154] stopping host 192.168.122.101 successfully +``` + +停止集群的更多参数,请查看帮助文档: + +```shell +# ptk cluster stop -h +停止数据库实例或集群 + +Usage: + ptk cluster stop [flags] + +Flags: + -h, --help help for stop + -H, --host string 操作的实例IP + -n, --name string 集群名称 + --time-out duration 停止超时时间 (default 10m0s) +``` + +### 重启集群 + +> 下面的集群操作以集群 `cluster_slirist` 为例 + +重启集群的操作,本质上是先停止数据库,再启动数据库的组合操作。 + +可通过 `cluster restart` 指令来实现: + +```shell +# ptk cluster -n cluster_slirist restart +INFO[2022-08-02T11:59:31.037] Operating: Stopping. +INFO[2022-08-02T11:59:31.037] ========================================= +INFO[2022-08-02T11:59:31.217] stopping host 192.168.122.102 +INFO[2022-08-02T11:59:32.269] stopping host 192.168.122.102 successfully +INFO[2022-08-02T11:59:32.269] stopping host 192.168.122.101 +INFO[2022-08-02T11:59:33.309] stopping host 192.168.122.101 successfully +INFO[2022-08-02T11:59:33.309] ========================================= +INFO[2022-08-02T11:59:33.309] Successfully stoped. +INFO[2022-08-02T11:59:33.309] Operation succeeded: Stop. + +INFO[2022-08-02T11:59:33.310] Operating: Starting. +INFO[2022-08-02T11:59:33.310] ========================================= +INFO[2022-08-02T11:59:33.376] starting host 192.168.122.101 +INFO[2022-08-02T11:59:35.583] starting host 192.168.122.101 successfully +INFO[2022-08-02T11:59:35.583] starting host 192.168.122.102 +INFO[2022-08-02T11:59:36.787] starting host 192.168.122.102 successfully +INFO[2022-08-02T11:59:36.995] waiting for check cluster state... +INFO[2022-08-02T11:59:42.247] ========================================= +INFO[2022-08-02T11:59:42.247] Successfully started. +INFO[2022-08-02T11:59:42.247] Operation succeeded: Start. +``` + +重启集群的更多参数,请查看帮助文档: + +```shell +# ptk cluster restart -h +重启数据库实例或集群 + +Usage: + ptk cluster restart [flags] + +Flags: + -h, --help help for restart + -H, --host string 操作的实例IP + -n, --name string 集群名称 + --security-mode string 是否使用安全模式启动数据库 + 可选项: on/off + --time-out duration 启动超时时间 (default 10m0s) +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/1-routine-maintenance-check-items.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/1-routine-maintenance-check-items.md new file mode 100644 index 00000000..f4070e6d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/1-routine-maintenance-check-items.md @@ -0,0 +1,178 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 日常维护检查项 + +## 检查MogDB状态 + +通过MogDB提供的工具查询数据库和实例状态,确认数据库和实例都处于正常的运行状态,可以对外提供数据服务。 + +- 检查实例状态 + + ```bash + gs_check -U omm -i CheckClusterState + ``` + +- 检查参数 + + ```sql + MogDB=# SHOW parameter_name; + ``` + + 上述命令中,parameter_name需替换成具体的参数名称。 + +- 修改参数 + + ```bash + gs_guc reload -D /mogdb/data/dbnode -c "paraname=value" + ``` + +
+ +## 检查锁信息 + +锁机制是数据库保证数据一致性的重要手段,检查相关信息可以检查数据库的事务和运行状况。 + +- 查询数据库中的锁信息 + + ```sql + MogDB=# SELECT * FROM pg_locks; + ``` + +- 查询等待锁的线程状态信息 + + ```sql + MogDB=# SELECT * FROM pg_thread_wait_status WHERE wait_status = 'acquire lock'; + ``` + +- 结束系统进程 + + 查找正在运行的系统进程,然后使用kill命令结束此进程。 + + ```bash + ps ux + kill -9 pid + ``` + +
+ +## 统计事件数据 + +SQL语句长时间运行会占用大量系统资源,用户可以通过查看事件发生的时间,占用内存大小来了解现在数据库运行状态。 + +- 查询事件的时间 + + 查询事件的线程启动时间、事务启动时间、SQL启动时间以及状态变更时间。 + + ```sql + MogDB=# SELECT backend_start,xact_start,query_start,state_change FROM pg_stat_activity; + ``` + +- 查询当前服务器的会话计数信息 + + ```sql + MogDB=# SELECT count(*) FROM pg_stat_activity; + ``` + +- 查询系统级统计信息 + + 查询当前使用内存最多的会话信息。 + + ```sql + MogDB=# SELECT * FROM pv_session_memory_detail() ORDER BY usedsize desc limit 10; + ``` + +
+ +## 对象检查 + +表、索引、分区、约束等是数据库的核心存储对象,其核心信息和对象维护是DBA重要的日常工作。 + +- 查看表的详细信息 + + ```sql + MogDB=# \d+ table_name + ``` + +- 查询表统计信息 + + ```sql + MogDB=# SELECT * FROM pg_statistic; + ``` + +- 查看索引的详细信息 + + ```sql + MogDB=# \d+ index_name + ``` + +- 查询分区表信息 + + ```sql + MogDB=# SELECT * FROM pg_partition; + ``` + +- 收集统计信息 + + 使用ANALYZE语句收集数据库相关的统计信息。 + + 使用VACUUM语句可以回收空间并更新统计信息。 + +- 查询约束信息 + + ```sql + MogDB=# SELECT * FROM pg_constraint; + ``` + +
+ +## SQL报告检查 + +使用EXPLAIN语句查看执行计划。 + +
+ +### 备份 + +数据备份重于一切,日常应检查备份执行情况,并检查备份有效性,确保备份能够保障数据安全,备份安全加密也应兼顾。 + +- 指定用户导出数据库 + + ```bash + gs_dump dbname -p port -f out.sql -U user_name -W password + ``` + +- 导出schema + + ```bash + gs_dump dbname -p port -n schema_name -f out.sql + ``` + +- 导出table: + + ```bash + gs_dump dbname -p port -t table_name -f out.sql + ``` + +
+ +### 基本信息检查 + +基本信息包括版本、组件、补丁集等信息,定期检查数据库信息并登记在案是数据库生命周期管理的重要内容之一。 + +- 版本信息 + + ```sql + MogDB=# SELECT version(); + ``` + +- 容量检查 + + ```sql + MogDB=# SELECT pg_table_size('table_name'); + MogDB=# SELECT pg_database_size('database_name'); + ``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/10-data-security-maintenance-suggestions.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/10-data-security-maintenance-suggestions.md new file mode 100644 index 00000000..dd1db269 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/10-data-security-maintenance-suggestions.md @@ -0,0 +1,29 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 数据安全维护建议 + +为保证MogDB数据库中的数据安全,避免丢失数据,非法访问数据等事故发生,请仔细阅读以下内容。 + +**避免数据被丢失** + +建议用户规划周期性的物理备份,且对备份文件进行可靠的保存。在系统发生严重错误的情况下,可以利用备份文件,将系统恢复到备份前的状态。 + +**避免数据被非法访问** + +- 建议对数据库用户进行权限分级管理。数据库管理员根据业务需要,建立用户并赋予权限,保证各用户对数据库的合理访问。 +- 对于MogDB的服务端和客户端(或基于客户端库开发的应用程序),最好也部署在可信任的内网中。如果服务端和客户端一定要部署在非信任的网络中,需要在服务启动前,打开SSL加密,保证数据在非信任网络上的传输安全。需要注意的是,打开SSL加密会降低数据库的性能。 + +**避免系统日志泄露个人数据** + +- 将调试日志发给他人进行分析前,请删除个人数据。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** 因为日志级别(log_min_messages)设置为DEBUGx(x为DEBUG级别,取值范围为1~5)时,调试日志中记录的信息可能包含用户的个人数据。 + +- 将系统日志发给其他人进行分析前,请删除个人数据。因为在默认配置下,当SQL语句执行错误时,日志中会记录出错的SQL语句,而这些SQL语句中可能包含用户个人数据。 + +- 将log_min_error_statement参数的值设置为PANIC,可以避免将出错的SQL语句记录在系统日志中。若禁用该功能,当出现故障时,很难定位故障原因。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/11-log-reference.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/11-log-reference.md new file mode 100644 index 00000000..9a5ade00 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/11-log-reference.md @@ -0,0 +1,153 @@ +--- +title: 日志参考 +summary: 日志参考 +author: Guo Huan +date: 2021-06-24 +--- + +# 日志参考 + +## 日志类型简介 + +在数据库运行过程中,会出现大量日志,既有保证数据库安全可靠的WAL日志(预写式日志,也称为Xlog),也有用于数据库日常维护的运行和操作日志等。在数据库发生故障时,可以参考这些日志进行问题定位和数据库恢复的操作。 + +**日志类型** + +日志类型的详细说明请参见下表。 + +**表 1** 日志类型 + +| 类型 | 说明 | +| :--------- | :----------------------------------------------------------- | +| 系统日志 | 数据库系统进程运行时产生的日志,记录系统进程的异常信息。 | +| 操作日志 | 通过客户端工具(例如gs_guc)操作数据库时产生的日志。 | +| Trace日志 | 打开数据库的调试开关后,会记录大量的Trace日志。这些日志可以用来分析数据库的异常信息。 | +| 黑匣子日志 | 数据库系统崩溃的时候,通过故障现场堆、栈信息可以分析出故障发生时的进程上下文,方便故障定位。黑匣子具有在系统崩溃时,dump出进程和线程的堆、栈、寄存器信息的功能。 | +| 审计日志 | 开启数据库审计功能后,将数据库用户的某些操作记录在日志中,这些日志称为审计日志。 | +| WAL日志 | 又称为REDO日志,在数据库异常损坏时,可以利用WAL日志进行恢复。由于WAL日志的重要性,所以需要经常备份这些日志。 | +| 性能日志 | 数据库系统在运行时检测物理资源的运行状态的日志,在对外部资源进行访问时的性能检测,包括磁盘、Hadoop MogDB等外部资源的访问检测信息。 | + +## 系统日志 + +MogDB运行时数据库节点以及MogDB安装部署时产生的日志统称为系统日志。如果MogDB在运行时发生故障,可以通过这些系统日志及时定位故障发生的原因,根据日志内容制定恢复MogDB的方法。 + +**日志文件存储路径** + +数据库节点的运行日志放在“/var/log/mogdb/用户名/pg_log”中各自对应的目录下。 + +OM MogDB安装卸载时产生的日志放在“/var/log/mogdb/用户名/om”目录下。 + +**日志文件命名格式** + +- 数据库节点运行日志的命名规则: + + postgresql-创建时间.log + + 默认情况下,每日0点或者日志文件大于16MB或者数据库实例(数据库节点)重新启动后,会生成新的日志文件。 + +- CM的运行日志的命名规则: + + - cm_agent的日志:cm_agent-创建时间.log、cm_agent-创建时间-current.log、system_call-创建时间.log、system_call-创建时间-current.log。 + - cm_server的日志:cm_server-创建时间.log、cm_server-创建时间-current.log;key_event-创建时间.log、key_event-创建时间-current.log。 + - om_monitor的日志:om_monitor-创建时间.log、om_monitor-创建时间-current.log。 + + 其中,不带current标识符的文件是历史日志文件,带current标识符的文件是当前日志文件。最初调用进程时,进程会先创建一个带current标识符的日志文件,当该日志文件的大小超过16MB时,会将当前日志文件重命名为历史日志文件,并以当前时间生成新的当前日志文件。 + +**日志内容说明** + +- 数据库节点每一行日志内容的默认格式: + + 日期+时间+时区+用户名称+数据库名称+会话ID+日志级别+日志内容 + +- cm_agent、cm_server、om_monitor每一行日志内容的默认格式: + + 时间+时区+会话ID+日志内容 + SYSTEM_CALL系统调用日志记录了CM_AGENT在运行过程中调用工具命令的情况。 + key_event每一行日志内容的默认格式: 时间+线程号+线程名: 关键事件类型+仲裁对象实例ID+仲裁细节。 + +## 操作日志 + +操作日志是指数据库管理员使用工具操作数据库时以及工具被MogDB调用时产生的日志。如果MogDB发生故障,可以通过这些日志信息跟踪用户对数据库进行了哪些操作,重现故障场景。 + +**日志文件存储路径** + +默认在`$GAUSSLOG/bin`目录下, 如果环境变量`$GAUSSLOG`不存在或者变量值为空,则工具日志信息不会记录到对应的工具日志文件中,日志信息只会打印到屏幕上。 + +其中`$GAUSSLOG`默认为`/var/log/mogdb/_用户名_`。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> 如果使用om脚本部署时,则日志路径为`/var/log/mogdb/_用户名_`。 + +**日志文件命名格式** + +日志文件命名格式为: + +- 工具名-日志创建时间.log +- 工具名-日志创建时间-current.log + +其中,“工具名-日志创建时间.log”是历史日志文件,“工具名-日志创建时间-current.log”是当前日志文件。 + +如果日志大小超过16MB,在下一次调用该工具时,会重命名当前日志文件为历史日志文件,并以当前时间生成新的当前日志文件。 + +例如将“gs_guc-2015-01-16_183728-current.log”重命名为“gs_guc-2015-01-16_183728.log”,然后重新生成“gs_guc-2015-01-17_142216-current.log”。 + +**维护建议** + +建议定时对过期的日志文件进行转储,以避免大量日志占用太多的磁盘空间和避免重要日志丢失。 + +## 审计日志 + +审计功能开启时会不断产生大量的审计日志,占用磁盘空间。用户可以根据磁盘空间的大小设置审计日志维护策略。 + +关于如何设置审计日志维护策略请参见《数据库安全管理》中设置数据库审计 > 维护审计日志”章节。 + +## WAL日志 + +预写式日志WAL(Write Ahead Log,也称为Xlog)是实现事务日志的标准方法,对数据文件(表和索引的载体)持久化修改之前必须先持久化相应的日志。如果要修改数据文件,必须是在这些修改操作已经记录到日志文件之后才能进行修改,即在描述这些变化的日志记录刷新到永久存储器之后。在系统崩溃时,可以使用WAL日志对MogDB进行恢复操作。 + +**日志文件存储路径** + +以一个数据库节点为例,默认在`/mogdb/data/data_dn/pg_xlog`目录下。 + +其中`/mogdb/data/data_dn`代表MogDB节点的数据目录。 + +**日志文件命名格式** + +日志文件以段文件的形式存储的,每个段为16MB,并分割成若干页,每页8KB。对WAL日志的命名说明如下:一个段文件的名称由24个十六进制组成,分为三个部分,每个部分由8个十六进制字符组成。第一部分表示时间线,第二部分表示日志文件标号,第三部分表示日志文件的段标号。时间线由1开始,日志文件标号和日志文件的段标号由0开始。 + +例如,系统中的第一个事务日志文件是000000010000000000000000。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> 这些数字一般情况下是顺序增长使用的(要把所有可用数字都用光也需要非常长的时间),但也存在循环使用的情况。 + +**日志内容说明** + +WAL日志的内容取决于记录事务的类型,在系统崩溃时可以利用WAL日志进行恢复。 + +默认配置下,MogDB每次启动时会先读取WAL日志进行恢复。 + +**维护建议** + +WAL日志对数据库异常恢复有重要的作用,建议定期对WAL日志进行备份。 + +## 性能日志 + +性能日志主要关注外部资源的访问性能问题。性能日志指的是数据库系统在运行时检测物理资源的运行状态的日志,在对外部资源进行访问时的性能检测,包括磁盘、Hadoop MogDB等外部资源的访问检测信息。在出现性能问题时,可以借助性能日志及时的定位问题发生的原因,能极大地提升问题解决效率。 + +**日志文件存储路径** + +数据库节点的性能日志目录在“$GAUSSLOG/gs_profile”中各自对应的目录下。 + +**日志文件命名格式** + +数据库节点的性能日志的命名规则: + +postgresql-创建时间.prf + +默认情况下,每日0点或者日志文件大于20MB或者数据库实例(数据库节点)重新启动后,会生成新的日志文件。 + +**日志内容说明** + +数据库节点每一行日志内容的默认格式: + +主机名称+日期+时间+实例名称+线程号+日志内容。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/2-checking-os-parameters.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/2-checking-os-parameters.md new file mode 100644 index 00000000..1ae3f59c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/2-checking-os-parameters.md @@ -0,0 +1,180 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 检查操作系统参数 + +## 检查办法 + +通过MogDB提供的gs_checkos工具可以完成操作系统状态检查。 + +**前提条件** + +- 当前的硬件和网络环境正常。 +- 各主机间root互信状态正常。 +- 只能使用root用户执行gs_checkos命令。 + +**操作步骤** + +1. 以root用户身份登录任意一台服务器。 + +2. 执行如下命令对MogDB节点服务器的OS参数进行检查。 + + ``` + gs_checkos -i A + ``` + + 检查节点服务器的OS参数的目的是保证MogDB正常通过预安装,并且在安装成功后可以安全高效的运行。详细的检查项目请参见《参考指南》中“工具参考 > 服务端工具 > [gs_checkos](../../reference-guide/tool-reference/server-tools/2-gs_checkos.md)”章节。 + +**示例** + +执行gs_checkos前需要先使用gs_preinstall工具执行前置脚本,准备环境。以参数“A”为例。 + +``` +gs_checkos -i A +Checking items: + A1. [ OS version status ] : Normal + A2. [ Kernel version status ] : Normal + A3. [ Unicode status ] : Normal + A4. [ Time zone status ] : Normal + A5. [ Swap memory status ] : Normal + A6. [ System control parameters status ] : Normal + A7. [ File system configuration status ] : Normal + A8. [ Disk configuration status ] : Normal + A9. [ Pre-read block size status ] : Normal + A10.[ IO scheduler status ] : Normal + A11.[ Network card configuration status ] : Normal + A12.[ Time consistency status ] : Warning + A13.[ Firewall service status ] : Normal + A14.[ THP service status ] : Normal +Total numbers:14. Abnormal numbers:0. Warning number:1. +``` + +以参数“B”为例。 + +``` +gs_checkos -i B +Setting items: + B1. [ Set system control parameters ] : Normal + B2. [ Set file system configuration value ] : Normal + B3. [ Set pre-read block size value ] : Normal + B4. [ Set IO scheduler value ] : Normal + B5. [ Set network card configuration value ] : Normal + B6. [ Set THP service ] : Normal + B7. [ Set RemoveIPC value ] : Normal + B8. [ Set Session Process ] : Normal +Total numbers:6. Abnormal numbers:0. Warning number:0. +``` + +
+ +## 异常处理 + +使用gs_checkos检查MogDB状态,可以使用如下命令查看详细的错误信息。 + +``` +gs_checkos -i A --detail +``` + +其中,Abnormal为必须处理项,影响MogDB安装。Warning可以不处理,不会影响MogDB安装。 + +- 如果操作系统版本(A1)检查项检查结果为Abnormal,需要将不属于混编范围的操作系统版本替换为混编范围内的操作系统版本。 + +- 如果内核版本(A2)检查项检查结果为Warning,则表示MogDB内平台的内核版本不一致。 + +- 如果Unicode状态(A3)检查项检查结果为Abnormal,需要将各主机的字符集设置为相同的字符集,可以在/etc/profile文件中添加“export LANG=XXX”(XXX为Unicode编码)。 + + ``` + vim /etc/profile + ``` + +- 如果时区状态(A4)检查项检查结果为Abnormal,需要将各主机的时区设置为相同时区,可以将/usr/share/zoneinfo/目录下的时区文件拷贝为/etc/localtime文件。 + + ``` + cp /usr/share/zoneinfo/$地区/$时区 /etc/localtime + ``` + +- 如果交换内存状态(A5)检查项检查结果为Abnormal,可能是因为swap空间大于mem空间,可减小Swap解决或者增大Mem空间解决。 + +- 如果系统控制参数(A6)检查项检查结果为Abnormal,可以使用以下两种方法进行设置。 + + - 可以使用如下命令进行设置。 + + ``` + gs_checkos -i B1 + ``` + + - 根据错误提示信息,在/etc/sysctl.conf文件中进行设置。然后执行sysctl -p使其生效。 + + ``` + vim /etc/sysctl.conf + ``` + +- 如果文件系统配置状态(A7)检查项检查结果为Abnormal,可以使用如下命令进行设置。 + + ``` + gs_checkos -i B2 + ``` + +- 如果磁盘配置状态(A8)检查项检查结果为Abnormal,需修改磁盘挂载格式为: "rw,noatime,inode64,allocsize=16m"。 + + 使用linux的man mount命令挂载XFS选项: + + ``` + rw,noatime,inode64,allocsize=16m + ``` + + 也可以在/etc/fstab文件中设定XFS选项。如下示例: + + ``` + /dev/data /data xfs rw,noatime,inode64,allocsize=16m 0 0 + ``` + +- 如果预读块大小(A9)检查项检查结果为Abnormal,可以使用如下命令进行设置。 + + ``` + gs_checkos -i B3 + ``` + +- 如果IO调度状态(A10)检查项检查结果为Abnormal,可以使用如下命令进行设置。 + + ``` + gs_checkos -i B4 + ``` + +- 如果网卡配置状态(A11)检查项检查结果为Warning,可以使用如下命令进行设置。 + + ``` + gs_checkos -i B5 + ``` + +- 如果时间一致性(A12)检查项检查结果为Abnormal,需检查是否安装ntp服务,以及ntp服务是否启动;并与ntp时钟源同步。 + +- 如果防火墙状态(A13)检查项检查结果为Abnormal,需关闭防火墙服务。使用如下命令进行设置。 + + - SuSE: + + ``` + SuSEfirewall2 stop + ``` + + - RedHat7: + + ``` + systemctl disable firewalld + ``` + + - RedHat6: + + ``` + service iptables stop + ``` + +- 如果THP服务(A14)检查项检查结果为Abnormal,可以使用如下命令进行设置。 + + ``` + gs_checkos -i B6 + ``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/3-checking-mogdb-health-status.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/3-checking-mogdb-health-status.md new file mode 100644 index 00000000..ca6452ac --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/3-checking-mogdb-health-status.md @@ -0,0 +1,648 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 检查MogDB健康状态 + +## 检查办法 + +通过MogDB提供的gs_check工具可以开展MogDB健康状态检查。 + +**注意事项** + +- 扩容新节点检查只能在root用户下执行,其他场景都必须在omm用户下执行。 +- 必须指定-i或-e参数,-i会检查指定的单项,-e会检查对应场景配置中的多项。 +- 如果-i参数中不包含root类检查项或-e场景配置列表中没有root类检查项,则不需要交互输入root权限的用户及其密码。 +- 可使用-skip-root-items跳过检查项中包含的root类检查,以免需要输入root权限用户及密码。 +- 检查扩容新节点与现有节点之间的一致性,在现有节点执行gs_check命令指定-hosts参数进行检查,其中hosts文件中需要写入新节点ip。 + +**操作步骤** + +方式1: + +1. 以操作系统用户omm登录数据库主节点。 + +2. 执行如下命令对MogDB数据库状态进行检查。 + + ```bash + gs_check -i CheckClusterState + ``` + + 其中,-i指定检查项,注意区分大小写。格式: -i CheckClusterState、-i CheckCPU或-i CheckClusterState,CheckCPU。 + + 取值范围为所有支持的检查项名称,详细列表请参见“参考指南 > 工具参考 > 服务端工具 > [gs_check](../../reference-guide/tool-reference/server-tools/1-gs_check.md)”中的“表 1 MogDB状态检查表”,用户可以根据需求自己编写新检查项。 + +方式2: + +1. 以操作系统用户omm登录数据库主节点。 + +2. 执行如下命令对MogDB数据库进行健康检查。 + + ```bash + gs_check -e inspect + ``` + + 其中,-e指定场景名,注意区分大小写。格式: -e inspect或-e upgrade。 + + 取值范围为所有支持的巡检场景名称,默认列表包括: inspect(例行巡检)、upgrade(升级前巡检)、install(安装)、binary_upgrade(就地升级前巡检)、health(健康检查巡检)、slow_node(节点)、longtime(耗时长巡检),用户可以根据需求自己编写场景。 + +MogDB巡检的主要作用是在MogDB运行过程中,检查整个MogDB状态是否正常,或者重大操作前(升级、扩容),确保MogDB满足操作所需的环境条件和状态条件。详细的巡检项目和场景请参见《MogDB 工具参考》中"服务端工具 > [gs_checkos](../../reference-guide/tool-reference/server-tools/2-gs_checkos.md) > MogDB状态检查表"。 + +**示例** + +执行单项检查结果: + +```bash +perfadm@lfgp000700749:/opt/huawei/perfadm/tool/script> gs_check -i CheckCPU +Parsing the check items config file successfully +Distribute the context file to remote hosts successfully +Start to health check for the cluster. Total Items:1 Nodes:3 + +Checking... [=========================] 1/1 +Start to analysis the check result +CheckCPU....................................OK +The item run on 3 nodes. success: 3 + +Analysis the check result successfully +Success. All check items run completed. Total:1 Success:1 Failed:0 +For more information please refer to /opt/mogdb/tools/script/gspylib/inspection/output/CheckReport_201902193704661604.tar.gz +``` + +本地执行结果: + +```bash +perfadm@lfgp000700749:/opt/huawei/perfadm/tool/script> gs_check -i CheckCPU -L + +2017-12-29 17:09:29 [NAM] CheckCPU +2017-12-29 17:09:29 [STD] 检查主机CPU占用率,如果idle 大于30%并且iowait 小于 30%.则检查项通过,否则检查项不通过 +2017-12-29 17:09:29 [RST] OK + +2017-12-29 17:09:29 [RAW] +Linux 4.4.21-69-default (lfgp000700749) 12/29/17 _x86_64_ + +17:09:24 CPU %user %nice %system %iowait %steal %idle +17:09:25 all 0.25 0.00 0.25 0.00 0.00 99.50 +17:09:26 all 0.25 0.00 0.13 0.00 0.00 99.62 +17:09:27 all 0.25 0.00 0.25 0.13 0.00 99.37 +17:09:28 all 0.38 0.00 0.25 0.00 0.13 99.25 +17:09:29 all 1.00 0.00 0.88 0.00 0.00 98.12 +Average: all 0.43 0.00 0.35 0.03 0.03 99.17 +``` + +执行场景检查结果: + +```bash +[perfadm@SIA1000131072 Check]$ gs_check -e inspect +Parsing the check items config file successfully +The below items require root privileges to execute:[CheckBlockdev CheckIOrequestqueue CheckIOConfigure CheckCheckMultiQueue CheckFirewall CheckSshdService CheckSshdConfig CheckCrondService CheckBootItems CheckFilehandle CheckNICModel CheckDropCache] +Please enter root privileges user[root]:root +Please enter password for user[root]: +Please enter password for user[root] on the node[10.244.57.240]: +Check root password connection successfully +Distribute the context file to remote hosts successfully +Start to health check for the cluster. Total Items:57 Nodes:2 + +Checking... [ ] 21/57 +Checking... [=========================] 57/57 +Start to analysis the check result +CheckClusterState...........................OK +The item run on 2 nodes. success: 2 + +CheckDBParams...............................OK +The item run on 1 nodes. success: 1 + +CheckDebugSwitch............................OK +The item run on 2 nodes. success: 2 + +CheckDirPermissions.........................OK +The item run on 2 nodes. success: 2 + +CheckReadonlyMode...........................OK +The item run on 1 nodes. success: 1 + +CheckEnvProfile.............................OK +The item run on 2 nodes. success: 2 (consistent) +The success on all nodes value: +GAUSSHOME /usr1/mogdb/app +LD_LIBRARY_PATH /usr1/mogdb/app/lib +PATH /usr1/mogdb/app/bin + + +CheckBlockdev...............................OK +The item run on 2 nodes. success: 2 + +CheckCurConnCount...........................OK +The item run on 1 nodes. success: 1 + +CheckCursorNum..............................OK +The item run on 1 nodes. success: 1 + +CheckPgxcgroup..............................OK +The item run on 1 nodes. success: 1 + +CheckDiskFormat.............................OK +The item run on 2 nodes. success: 2 + +CheckSpaceUsage.............................OK +The item run on 2 nodes. success: 2 + +CheckInodeUsage.............................OK +The item run on 2 nodes. success: 2 + +CheckSwapMemory.............................OK +The item run on 2 nodes. success: 2 + +CheckLogicalBlock...........................OK +The item run on 2 nodes. success: 2 + +CheckIOrequestqueue.....................WARNING +The item run on 2 nodes. warning: 2 +The warning[host240,host157] value: +On device (vdb) 'IO Request' RealValue '256' ExpectedValue '32768' +On device (vda) 'IO Request' RealValue '256' ExpectedValue '32768' + +CheckMaxAsyIOrequests.......................OK +The item run on 2 nodes. success: 2 + +CheckIOConfigure............................OK +The item run on 2 nodes. success: 2 + +CheckMTU....................................OK +The item run on 2 nodes. success: 2 (consistent) +The success on all nodes value: +1500 + +CheckPing...................................OK +The item run on 2 nodes. success: 2 + +CheckRXTX...................................NG +The item run on 2 nodes. ng: 2 +The ng[host240,host157] value: +NetWork[eth0] +RX: 256 +TX: 256 + + +CheckNetWorkDrop............................OK +The item run on 2 nodes. success: 2 + +CheckMultiQueue.............................OK +The item run on 2 nodes. success: 2 + +CheckEncoding...............................OK +The item run on 2 nodes. success: 2 (consistent) +The success on all nodes value: +LANG=en_US.UTF-8 + +CheckFirewall...............................OK +The item run on 2 nodes. success: 2 + +CheckKernelVer..............................OK +The item run on 2 nodes. success: 2 (consistent) +The success on all nodes value: +3.10.0-957.el7.x86_64 + +CheckMaxHandle..............................OK +The item run on 2 nodes. success: 2 + +CheckNTPD...................................OK +host240: NTPD service is running, 2020-06-02 17:00:28 +host157: NTPD service is running, 2020-06-02 17:00:06 + + +CheckOSVer..................................OK +host240: The current OS is centos 7.6 64bit. +host157: The current OS is centos 7.6 64bit. + + +CheckSysParams..........................WARNING +The item run on 2 nodes. warning: 2 +The warning[host240,host157] value: +Warning reason: variable 'net.ipv4.tcp_retries1' RealValue '3' ExpectedValue '5'. +Warning reason: variable 'net.ipv4.tcp_syn_retries' RealValue '6' ExpectedValue '5'. + +CheckTHP....................................OK +The item run on 2 nodes. success: 2 + +CheckTimeZone...............................OK +The item run on 2 nodes. success: 2 (consistent) +The success on all nodes value: ++0800 + +CheckCPU....................................OK +The item run on 2 nodes. success: 2 + +CheckSshdService............................OK +The item run on 2 nodes. success: 2 + +Warning reason: UseDNS parameter is not set; expected: no + +CheckCrondService...........................OK +The item run on 2 nodes. success: 2 + +CheckStack..................................OK +The item run on 2 nodes. success: 2 (consistent) +The success on all nodes value: +8192 + +CheckSysPortRange...........................OK +The item run on 2 nodes. success: 2 + +CheckMemInfo................................OK +The item run on 2 nodes. success: 2 (consistent) +The success on all nodes value: +totalMem: 31.260929107666016G + +CheckHyperThread............................OK +The item run on 2 nodes. success: 2 + +CheckTableSpace.............................OK +The item run on 1 nodes. success: 1 + +CheckSysadminUser...........................OK +The item run on 1 nodes. success: 1 + + +CheckGUCConsistent..........................OK +All DN instance guc value is consistent. + +CheckMaxProcMemory..........................OK +The item run on 1 nodes. success: 1 + +CheckBootItems..............................OK +The item run on 2 nodes. success: 2 + +CheckHashIndex..............................OK +The item run on 1 nodes. success: 1 + +CheckPgxcRedistb............................OK +The item run on 1 nodes. success: 1 + +CheckNodeGroupName..........................OK +The item run on 1 nodes. success: 1 + +CheckTDDate.................................OK +The item run on 1 nodes. success: 1 + +CheckDilateSysTab...........................OK +The item run on 1 nodes. success: 1 + +CheckKeyProAdj..............................OK +The item run on 2 nodes. success: 2 + +CheckProStartTime.......................WARNING +host157: +STARTED COMMAND +Tue Jun 2 16:57:18 2020 /usr1/dmuser/dmserver/metricdb1/server/bin/mogdb --single_node -D /usr1/dmuser/dmb1/data -p 22204 +Mon Jun 1 16:15:15 2020 /usr1/mogdb/app/bin/mogdb -D /usr1/mogdb/data/dn1 -M standby + + +CheckFilehandle.............................OK +The item run on 2 nodes. success: 2 + +CheckRouting................................OK +The item run on 2 nodes. success: 2 + +CheckNICModel...............................OK +The item run on 2 nodes. success: 2 (consistent) +The success on all nodes value: +version: 1.0.1 +model: Red Hat, Inc. Virtio network device + + +CheckDropCache..........................WARNING +The item run on 2 nodes. warning: 2 +The warning[host240,host157] value: +No DropCache process is running + +CheckMpprcFile..............................NG +The item run on 2 nodes. ng: 2 +The ng[host240,host157] value: +There is no mpprc file + +Analysis the check result successfully +Failed. All check items run completed. Total:57 Success:50 Warning:5 NG:2 +For more information please refer to /usr1/mogdb/tool/script/gspylib/inspection/output/CheckReport_inspect611.tar.gz +``` + +
+ +## 异常处理 + +如果发现检查结果异常,可以根据以下内容进行修复。 + +**表 1** 检查MogDB运行状态 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
检查项 异常状态 处理方法
CheckClusterState(检查MogDB状态) MogDB未启动或MogDB实例未启动 使用以下命令启动MogDB及实例。
gs_om -t start
MogDB状态异常或MogDB实例异常 检查各主机、实例状态,根据状态信息进行排查。
gs_check -i CheckClusterState
CheckDBParams(检查数据库参数) 数据库参数错误 通过gs_guc工具修改数据库参数为指定值。
CheckDebugSwitch(检查调试日志) 日志级别不正确 使用gs_guc工具将log_min_messages改为指定内容。
CheckDirPermissions(检查目录权限) 路径权限错误 修改对应目录权限为指定数值(750/700)。
chmod 750 DIR
CheckReadonlyMode(检查只读模式) 只读模式被打开 确认数据库节点所在磁盘使用率未超阈值(默认60%)且未在执行其他运维操作。
gs_check -i CheckDataDiskUsage ps ux
使用gs_guc工具关闭MogDB只读模式。
gs_guc reload -N all -I all -c 'default_transaction_read_only = off'
CheckEnvProfile(检查环境变量) 环境变量不一致 重新执行前置更新环境变量信息。
CheckBlockdev(检查磁盘预读块) 磁盘预读块大小不为16384 使用gs_checkos设置预读块大小为16384KB,并写入自启动文件。
gs_checkos -i B3
CheckCursorNum(检查游标数) 检查游标数失败 检查数据库能否正常连接,MogDB状态是否正常。
CheckPgxcgroup(检查重分布状态) 有未完成重分布的pgxc_group表 继续完成扩容或缩容的数据重分布操作。
gs_expand、gs_shrink
CheckDiskFormat(检查磁盘配置) 各节点磁盘配置不一致 将各节点的磁盘规格改为相同。
CheckSpaceUsage(检查磁盘空间使用率) 磁盘可用空间不足 清理或扩展对应目录所在的磁盘。
CheckInodeUsage(检查磁盘索引使用率) 磁盘可用索引不足 清理或扩展对应目录所在的磁盘。
CheckSwapMemory(检查交换内存) 交换内存大于物理内存 将交换内存调小或关闭。
CheckLogicalBlock(检查磁盘逻辑块) 磁盘逻辑块大小不为512 使用gs_checkos修改磁盘逻辑块大小为512KB,并写入开机自启动文件。
gs_checkos -i B4
CheckIOrequestqueue(检查IO请求) IO请求值不为32768 使用gs_checkos设置IO请求值为32768,并写入开机自启动文件。
gs_checkos -i B4
CheckCurConnCount(检查当前连接数) 当前连接数超过最大连接数的90% 断开未使用的数据库主节点连接。
CheckMaxAsyIOrequests(检查最大异步请求) 最大异步请求值小于104857600或当前节点数据库实例数乘以1048576 使用gs_checkos设置最大异步请求值为104857600和当前节点数据库实例数乘以1048576中的最大值。
gs_checkos -i B4
CheckMTU(检查MTU值) MTU值不一致 设置各节点的MTU一致为1500或8192。
ifconfig eth* MTU 1500
CheckIOConfigure(检查IO配置) IO配置不是deadline 使用gs_checkos设置IO配置为deadline,并写入开机自启动文件。
gs_checkos -i B4
CheckRXTX(检查RXTX值) 网卡RX/TX值不是4096 使用checkos设置MogDB使用的物理网卡RX/TX值为4096。
gs_checkos -i B5
CheckPing(检查网络通畅) 存在MogDB IP无法ping通 检查异常ip间网络设置和状态、防火墙状态。
CheckNetWorkDrop(检查网络丢包率) 网络通信丢包率高于1% 检查对应IP间网络负载、状态。
CheckMultiQueue(检查网卡多队列) 未开启网卡多队列并未将网卡中断绑定到不同CPU核心 开启网卡多队列并将网卡队列中断绑定到不同的CPU核心。
CheckEncoding(检查编码格式) 各节点编码格式不一致 在/etc/profile中写入一致的编码信息。
echo "export LANG=XXX" >> /etc/profile
CheckActQryCount(检查归档模式) 启用归档模式,归档目录不在主数据库节点目录下 关闭归档模式或者将归档目录设置在主数据库节点目录下。
CheckFirewall(检查防火墙) 防火墙未关闭 关闭防火墙服务。
systemctl disable firewalld.service
CheckKernelVer(检查内核版本) 节点间的内核版本不一致
CheckMaxHandle(检查最大文件句柄数) 最大文件句柄数小于1000000 设置91-nofile.conf/90-nofile.conf最大文件句柄数软硬限制为1000000。
gs_checkos -i B2
CheckNTPD(检查时间同步服务) NTPD服务未开启或时间误差超过一分钟 开启NTPD服务并设置时钟一致。
CheckSysParams(检查操作系统参数) 操作系统参数设置不满足要求 使用gs_checkos进行参数设置或手动设置。
gs_checkos -i B1 vim /etc/sysctl.conf
CheckTHP(检查THP服务) THP服务未开启 使用gs_checkos设置THP服务。
gs_checkos -i B6
CheckTimeZone(检查时区) 时区不一致 设置各节点为同一时区。
`cp /usr/share/zoneinfo/$地区/$时区 /etc/localtime`
CheckCPU(检查CPU) CPU占用过高或IO等待过高 进行CPU配置升级或磁盘性能升级。
CheckSshdService(检查SSHD服务) 未开启SSHD服务 启动SSHD服务并写入开机自启动文件。
service sshd start echo "server sshd start" >> initFile
CheckSshdConfig(检查SSHD配置) SSHD服务配置错误 设置SSHD服务,
PasswordAuthentication=no; MaxStartups=1000; UseDNS=yes; ClientAliveInterval=10800/ClientAliveInterval=0
并重启服务:
server sshd start
CheckCrondService(检查Crond服务) Crond服务未启动 安装Crond服务并启用。
CheckStack(检查堆栈大小) 堆栈大小小于3072 使用gs_checkos设置为3072并重启堆栈值过小进程。
gs_checkos -i B2
CheckSysPortRange(检查系统端口设置) 系统ip端口不在预期范围内或MogDB端口在系统ip端口内 设置系统ip端口范围参数到26000-65535之中;设置MogDB端口在系统ip端口范围外。
vim /etc/sysctl.conf
CheckMemInfo(检查内存信息) 各节点内存大小不一致 使用相同规格的物理内存。
CheckHyperThread(检查超线程) 未开启CPU超线程 开启CPU超线程。
CheckTableSpace(检查表空间) 表空间路径和MogDB路径存在嵌套或表空间路径相互存在嵌套 将表空间数据迁移到路径合法的表空间中。
+ +## 状态查询 + +**背景信息** + +MogDB支持查看整个MogDB的状态,通过查询结果确认MogDB或者单个主机的运行状态是否正常。 + +**前提条件** + +MogDB已经启动。 + +**操作步骤** + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用如下命令查询MogDB状态: + + ```bash + gs_om -t status --detail + ``` + + MogDB状态显示结果的参数说明请参见表1。 + + 若要查询某主机上的实例状态,请在命令中增加“-h”项。示例如下: + + ```bash + gs_om -t status -h plat2 + ``` + + 其中,plat2为待查询主机的名称。 + +**参数说明** + +**表 1** 节点角色说明 + +| 字段 | 字段含义 | 字段值 | +| :------------ | :------------------------------------- | :----------------------------------------------------------- | +| cluster_state | MogDB状态。显示整个MogDB是否运行正常。 | - Normal:表示MogDB可用,且数据有冗余备份。所有进程都在运行,主备关系正常。
- Unavailable:表示MogDB不可用。
- Degraded:表示MogDB可用,但存在故障的数据库节点、数据库主节点实例。 | +| node | 主机名称 | 表示该实例所在的主机名称。多AZ时会显示AZ编号。 | +| node_ip | 主机IP | 表示该实例所在的主机IP。 | +| instance | 实例ID | 表示该实例的ID。 | +| state | 实例角色 | - Normal:表示单主机实例。
- Primary:表示实例为主实例。
- Standby:表示实例为备实例。
- Cascade Standby:表示实例为级联备实例。
- Pending:表示该实例在仲裁阶段。
- Unknown:表示实例状态未知。
- Down:表示实例处于宕机状态。
- Abnormal:表示节点处于异常状态。
- Manually stopped:表示节点已经被手动停止。 | + +每个角色也存在不同的状态,例如启动,连接等,其各个状态说明如下: + +**表 2** 节点状态说明 + +| 状态 | 字段含义 | +| :------------- | :----------------------------------------------------------- | +| Normal | 表示节点启动正常 | +| Need repair | 当前节点需要修复 | +| Starting | 节点正在启动中 | +| Wait promoting | 节点正等待升级中,例如备机向主机发送升级请求后,正在等待主机回应时的状态 | +| Promoting | 备节点正在升级为主节点的状态 | +| Demoting | 节点正在降级中,如主机正在降为备机中 | +| Building | 备机启动失败,需要重建 | +| Catchup | 备节点正在追赶主节点 | +| Coredump | 节点程序崩溃 | +| Unknown | 节点状态未知 | + +当节点出现Need repair状态时,可能需要对该节点进行重建使其恢复正常,通常情况下,节点重建原因说明如下: + +**表3** 节点重建原因说明 + +| 状态 | 字段含义 | +| :-------------------- | :---------------------------------------------------- | +| Normal | 表示节点启动正常 | +| WAL segment removed | 主机日志WAL日志不存在,备机日志比主机日志新 | +| Disconnect | 备机不能连接主机 | +| Version not matched | 主备二进制版本不一致 | +| Mode not matched | 主备角色不匹配,例如两个备机互联 | +| System id not matched | 主备数据库系统id不一致,主备双机要求System ID必须一致 | +| Timeline not matched | 日志时间线不一致 | +| Unknown | 其他原因 | + +**示例** + +查看MogDB详细状态信息,含实例状态信息。 + +```bash +gs_om -t status --detail +[ Cluster State ] + +cluster_state : Normal +redistributing : No +current_az : AZ_ALL + +[ Datanode State ] + + node node_ip port instance state +----------------------------------------------------------------------------------------------------- +1 pekpopgsci00235 10.244.62.204 5432 6001 /opt/mogdb/cluster/data/dn1 P Primary Normal +2 pekpopgsci00238 10.244.61.81 5432 6002 /opt/mogdb/cluster/data/dn1 S Standby Normal +``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/4-checking-database-performance.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/4-checking-database-performance.md new file mode 100644 index 00000000..ba49801f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/4-checking-database-performance.md @@ -0,0 +1,85 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 检查数据库性能 + +## 检查办法 + +通过MogDB提供的性能统计工具gs_checkperf可以对硬件性能进行检查。 + +**前提条件** + +- MogDB运行状态正常。 +- 运行在数据库之上的业务运行正常。 + +**操作步骤** + +1. 以操作系统用户omm登录数据库主节点。 + +2. 执行如下命令对MogDB数据库进行性能检查。 + + ```bash + gs_checkperf + ``` + +具体的性能统计项目请参见“参考指南 > 工具参考 > 服务端工具 > [gs_checkperf](../../reference-guide/tool-reference/server-tools/3-gs_checkperf.md)”中的“表1 性能检查项”。 + +**示例** + +以简要格式在屏幕上显示性能统计结果。 + +```bash +gs_checkperf -i pmk -U omm +Cluster statistics information: + Host CPU busy time ratio : 1.43 % + MPPDB CPU time % in busy time : 1.88 % + Shared Buffer Hit ratio : 99.96 % + In-memory sort ratio : 100.00 % + Physical Reads : 4 + Physical Writes : 25 + DB size : 70 MB + Total Physical writes : 25 + Active SQL count : 2 + Session count : 3 +``` + +
+ +## 异常处理 + +使用gs_checkperf工具检查MogDB性能状态后,如果发现检查结果发现异常,可以根据以下内容进行修复。 + +**表 1** 检查MogDB级别性能状态 + +| 异常状态 | 处理方法 | +| ----------------- | -------------------------------------------------- | +| 主机CPU占有率高 | 1、更换和增加高性能的CPU。
2、使用top命令查看系统哪些进程的CPU占有率高,然后使用kill命令关闭没有使用的进程。
*top* | +| MogDB CPU占有率高 | 1、更换和增加高性能的CPU。
2、使用top命令查看数据库哪些进程的CPU占有率高,然后使用kill命令关闭没有使用的进程。
*top*
3、使用gs_expand工具扩容,增加新的主机均衡CPU占有率。 | +| 共享内存命中率低 | 1、扩大内存。
2、使用如下命令查看操作系统配置文件/etc/sysctl.conf,调大共享内存kernel.shmmax值。
*vim /etc/sysctl.conf* | +| 内存中排序比率低 | 扩大内存。 | +| I/O、磁盘使用率高 | 1、更换高性能的磁盘。
2、调整数据布局,尽量将I/O请求较合理的分配到所有物理磁盘中。
3、全库进行VACUUM FULL操作。
*vacuum full;*
4、进行磁盘整理。
5、降低并发数。 | +| 事务统计 | 查询pg_stat_activity系统表,将不必要的连接断开。(登录数据库后查询: postgres=# \d+ pg_stat_activity;) | + +**表 2** 检查节点级别性能状态 + +| 异常状态 | 处理方法 | +| ------------------ | --------------------------------------- | +| CPU占有率高 | 1、更换和增加高性能的CPU。
2、使用top命令查看系统哪些进程的CPU占有率高,然后使用kill命令关闭没有使用的进程。
*top* | +| 内存使用率过高情况 | 扩大或清理内存。 | +| I/O使用率过高情况 | 1、更换高性能的磁盘。
2、进行磁盘清理。
3、尽可能用内存的读写代替直接磁盘I/O,使频繁访问的文件或数据放入内存中进行操作处理。 | + +**表 3** 会话/进程级别性能状态 + +| 异常状态 | 处理方法 | +| ---------------------------- | --------------------------------- | +| CPU、内存、I/O使用率过高情况 | 查看哪个进程占用CPU/内存高或I/O使用率高,若是无用的进程,则kill掉,否则排查具体原因。例如SQL执行占用内存大,查看是否SQL语句需要优化。 | + +**表 4** SSD性能状态 + +| 异常状态 | 处理方法 | +| --------------- | -------------------------------------------- | +| SSD读写性能故障 | 使用以下命令查看SSD是否有故障,排查具体故障原因。
*gs_checkperf -i SSD -U omm* | diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/5-checking-and-deleting-logs.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/5-checking-and-deleting-logs.md new file mode 100644 index 00000000..d1ebaf92 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/5-checking-and-deleting-logs.md @@ -0,0 +1,164 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 检查和清理日志 + +日志是检查系统运行及故障定位的关键手段。建议按月度例行查看操作系统日志及数据库的运行日志。同时,随着时间的推移,日志的增加会占用较多的磁盘空间。建议按月度清理数据库的运行日志。 + +
+ +## 检查操作系统日志 + +建议按月检查操作系统日志,排除操作系统运行异常隐患。 + +执行如下命令查看操作系统日志文件。 + +``` +vim /var/log/messages +``` + +关注其中近一个月出现的kernel、error、fatal等字样,根据系统报警信息进行处理。 + +
+ +## 检查MogDB运行日志 + +数据库运行时,某些操作在执行过程中可能会出现错误,数据库依然能够运行。但是此时数据库中的数据可能已经发生不一致的情况。建议按月检查MogDB运行日志,及时发现隐患。 + +**前提条件** + +- 收集日志的主机网络通畅且未宕机,数据库安装用户互信正常。 +- 日志收集工具依赖操作系统工具如gstack,如果未安装该工具,则提示错误后,跳过该收集项。 + +**操作步骤** + +1. 以操作系统用户omm登录数据库主节点。 + +2. 执行如下命令收集数据库日志。 + + ```bash + gs_collector --begin-time="20160616 01:01" --end-time="20160616 23:59" + ``` + + 20160616 01:01为日志的开始时间,20160616 23:59为日志的结束时间。 + +3. 根据2的界面输出提示,进入相应的日志收集目录,解压收集的日志,并检查数据库日志。 + + 以下以日志收集路径"/opt/mogdb/tmp/gaussdba_mppdb/collector_20160726_105158.tar.gz"为例进行操作。 + + ``` + tar -xvzf /opt/mogdb/tmp/gaussdba_mppdb/collector_20160726_105158.tar.gz + cd /opt/mogdb/tmp/gaussdba_mppdb/collector_20160726_105158 + ``` + +**示例** + +- 以-begin-time与-end-time为参数执行gs_collector命令。 + + ```bash + gs_collector --begin-time="20160616 01:01" --end-time="20160616 23:59" + ``` + + 当显示类似如下信息表示日志已经归档。 + + ``` + Successfully collected files + All results are stored in /tmp/gaussdba_mppdb/collector_20160616_175615.tar.gz. + ``` + +- 以-begin-time,-end-time与-h为参数执行gs_collector命令。 + + ```bash + gs_collector --begin-time="20160616 01:01" --end-time="20160616 23:59" -h plat2 + ``` + + 当显示类似如下信息表示日志已经归档。 + + ``` + Successfully collected files + All results are stored in /tmp/gaussdba_mppdb/collector_20160616_190225.tar.gz. + ``` + +- 以-begin-time,-end-time与-f为参数执行gs_collector命令。 + + ```bash + gs_collector --begin-time="20160616 01:01" --end-time="20160616 23:59" -f /opt/software/mogdb/output + ``` + + 当显示类似如下信息表示日志已经归档。 + + ``` + Successfully collected files + All results are stored in /opt/software/mogdb/output/collector_20160616_190511.tar.gz. + ``` + +- 以-begin-time,-end-time与-keyword为参数执行gs_collector命令。 + + ```bash + gs_collector --begin-time="20160616 01:01" --end-time="20160616 23:59" --keyword="os" + ``` + + 当显示类似如下信息表示日志已经归档。 + + ``` + Successfully collected files. + All results are stored in /tmp/gaussdba_mppdb/collector_20160616_190836.tar.gz. + ``` + +- 以-begin-time,-end-time与-o为参数执行gs_collector命令。 + + ```bash + gs_collector --begin-time="20160616 01:01" --end-time="20160616 23:59" -o /opt/software/mogdb/output + ``` + + 当显示类似如下信息表示日志已经归档。 + + ``` + Successfully collected files. + All results are stored in /opt/software/mogdb/output/collector_20160726_113711.tar.gz. + ``` + +- 以-begin-time,-end-time与-l为参数(文件名必须以.log为后缀)执行gs_collector命令。 + + ```bash + gs_collector --begin-time="20160616 01:01" --end-time="20160616 23:59" -l /opt/software/mogdb/logfile.log + ``` + + 当显示类似如下信息表示日志已经归档。 + + ``` + Successfully collected files. + All results are stored in /opt/software/mogdb/output/collector_20160726_113711.tar.gz. + ``` + +
+ +## 清理运行日志 + +数据库运行过程中会产生大量运行日志,占用大量的磁盘空间,建议清理过期日志文件,只保留一个月的日志。 + +**操作步骤** + +1. 以操作系统用户omm登录数据库主节点。 + +2. 清理日志。 + + a. 将超过1个月的日志备份到其他磁盘。 + + b. 进入日志存放目录。 + + ``` + cd $GAUSSLOG + ``` + + c. 进入相应的子目录,使用如下方式删除1个月之前产生的日志。 + + ``` + rm 日志名称 + ``` + + 日志文件的命名格式为"mogdb-年-月-日_HHMMSS"。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/6-checking-time-consistency.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/6-checking-time-consistency.md new file mode 100644 index 00000000..5af18cfa --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/6-checking-time-consistency.md @@ -0,0 +1,52 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 检查时间一致性 + +数据库事务一致性通过逻辑时钟保证,与操作系统时间无关,但是系统时间不一致会导致诸多潜在问题,主要是后台运维和监控功能异常,因此在月度检查时建议检查各个节点的时间一致性。 + +**操作步骤** + +1. 以操作系统用户omm登录数据库主节点。 + +2. 创建记录MogDB各节点的配置文件(_mpphosts文件目录_用户可随意指定,建议放在/tmp下)。 + + ``` + vim /tmp/mpphosts + ``` + + 增加各节点的主机名称。 + + ``` + plat1 + plat2 + plat3 + ``` + +3. 保存配置文件。 + + ``` + :wq! + ``` + +4. 执行如下命令,输出各节点上的时间到"/tmp/sys_ctl-os1.log"文件中。 + + ``` + for ihost in `cat /tmp/mpphosts`; do ssh -n -q $ihost "hostname;date"; done > /tmp/ sys_ctl-os1.log + ``` + +5. 根据输出确认各个节点的时间一致性,节点之间时间差异不能超过30秒。 + + ``` + cat /tmp/sys_ctl-os1.log + plat1 + Thu Feb 9 16:46:38 CST 2017 + plat2 + Thu Feb 9 16:46:49 CST 2017 + plat3 + Thu Feb 9 16:46:14 CST 2017 + ``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/7-checking-the-number-of-application-connections.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/7-checking-the-number-of-application-connections.md new file mode 100644 index 00000000..e8457cbe --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/7-checking-the-number-of-application-connections.md @@ -0,0 +1,133 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 检查应用连接数 + +如果应用程序与数据库的连接数超过最大值,则新的连接无法建立。建议每天检查连接数,及时释放空闲的连接或者增加最大连接数。 + +**操作步骤** + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用如下命令连接数据库。 + + ```bash + gsql -d mogdb -p 8000 + ``` + + mogdb为需要连接的数据库名称,8000为数据库主节点的端口号。 + + 连接成功后,系统显示类似如下信息: + + ```bash + gsql ((MogDB x.x.x build 56189e20) compiled at 2022-01-07 18:47:53 commit 0 last mr ) + Non-SSL connection (SSL connection is recommended when requiring high-security) + Type "help" for help. + + MogDB=# + ``` + +3. 执行如下SQL语句查看连接数。 + + ```sql + MogDB=# SELECT count(*) FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS s; + ``` + + 显示类似如下的信息,其中2表示当前有两个应用连接到数据库。 + + ```sql + count + ------- + 2 + (1 row) + ``` + +4. 查看现有最大连接数。 + + ```sql + MogDB=# SHOW max_connections; + ``` + + 显示信息如下,其中200为现在的最大连接数。 + + ```sql + max_connections + ----------------- + 200 + (1 row) + ``` + +
+ +## 异常处理 + +如果显示的连接数接近数据库的最大连接数max_connections,则需要考虑清理现有连接数或者增加新的连接数。 + +1. 执行如下SQL语句,查看state字段等于idle,且state_change字段长时间没有更新过的连接信息。 + + ```sql + MogDB=# SELECT * FROM pg_stat_activity where state='idle' order by state_change; + ``` + + 显示类似如下的信息: + + ```sql + datid | datname | pid | usesysid | usename | application_name | client_addr + | client_hostname | client_port | backend_start | xact_start | quer + y_start | state_change | waiting | enqueue | state | resource_pool + | query + -------+----------+-----------------+----------+----------+------------------+--------------- + -+-----------------+-------------+-------------------------------+------------+-------------- + -----------------+-------------------------------+---------+---------+-------+--------------- + +---------------------------------------------- + 13626 | mogdb | 140390162233104 | 10 | gaussdba | | + | | -1 | 2016-07-15 14:08:59.474118+08 | | 2016-07-15 14 + :09:04.496769+08 | 2016-07-15 14:09:04.496975+08 | f | | idle | default_pool + | select count(group_name) from pgxc_group; + 13626 | mogdb | 140390132872976 | 10 | gaussdba | cn_5002 | 10.180.123.163 + | | 48614 | 2016-07-15 14:11:16.014871+08 | | 2016-07-15 14 + :21:17.346045+08 | 2016-07-15 14:21:17.346095+08 | f | | idle | default_pool + | SET SESSION AUTHORIZATION DEFAULT;RESET ALL; + (2 rows) + ``` + +2. 释放空闲的连接数。 + + 查看每个连接,并与此连接的使用者确认是否可以断开连接,或执行如下SQL语句释放连接。其中,pid为上一步查询中空闲连接所对应的pid字段值。 + + ```sql + MogDB=# SELECT pg_terminate_backend(140390132872976); + ``` + + 显示类似如下的信息: + + ```sql + MogDB=# SELECT pg_terminate_backend(140390132872976); + pg_terminate_backend + ---------------------- + t + (1 row) + ``` + + 如果没有可释放的连接,请执行下一步。 + +3. 增加最大连接数。 + + ```bash + gs_guc set -D /mogdb/data/dbnode -c "max_connections= 800" + ``` + + 其中800为新修改的连接数。 + +4. 重启数据库服务使新的设置生效。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > 重启MogDB操作会导致用户执行操作中断,请在操作之前规划好合适的执行窗口。 + + ```bash + gs_om -t stop && gs_om -t start + ``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/8-routinely-maintaining-tables.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/8-routinely-maintaining-tables.md new file mode 100644 index 00000000..79fbb036 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/8-routinely-maintaining-tables.md @@ -0,0 +1,111 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 例行维护表 + +为了保证数据库的有效运行,数据库必须在插入/删除操作后,基于客户场景,定期做VACUUM FULL和ANALYZE,更新统计信息,以便获得更优的性能。 + +**相关概念** + +使用VACUUM、VACUUM FULL和ANALYZE命令定期对每个表进行维护,主要有以下原因: + +- VACUUM FULL可回收已更新或已删除的数据所占据的磁盘空间,同时将小数据文件合并。 +- VACUUM对每个表维护了一个可视化映射来跟踪包含对别的活动事务可见的数组的页。一个普通的索引扫描首先通过可视化映射来获取对应的数组,来检查是否对当前事务可见。若无法获取,再通过堆数组抓取的方式来检查。因此更新表的可视化映射,可加速唯一索引扫描。 +- VACUUM可避免执行的事务数超过数据库阈值时,事务ID重叠造成的原有数据丢失。 +- ANALYZE可收集与数据库中表内容相关的统计信息。统计结果存储在系统表PG_STATISTIC中。查询优化器会使用这些统计数据,生成最有效的执行计划。 + +**操作步骤** + +1. 使用VACUUM或VACUUM FULL命令,进行磁盘空间回收。 + + - **VACUUM**: + + 对表执行VACUUM操作 + + ```sql + postgres=# VACUUM customer; + ``` + + ```sql + VACUUM + ``` + + 可以与数据库操作命令并行运行。(执行期间,可正常使用的语句: SELECT、INSERT、UPDATE和DELETE。不可正常使用的语句: ALTER TABLE)。 + + 对表分区执行VACUUM操作 + + ```sql + postgres=# VACUUM customer_par PARTITION ( P1 ); + ``` + + ```sql + VACUUM + ``` + + - **VACUUM FULL**: + + ```sql + postgres=# VACUUM FULL customer; + ``` + + ```sql + VACUUM + ``` + + 需要向正在执行的表增加排他锁,且需要停止其他所有数据库操作。 + +2. 使用ANALYZE语句更新统计信息。 + + ```sql + postgres=# ANALYZE customer; + ``` + + ```sql + ANALYZE + ``` + + 使用ANALYZE VERBOSE语句更新统计信息,并输出表的相关信息。 + + ```sql + postgres=# ANALYZE VERBOSE customer; + ``` + + ```sql + ANALYZE + ``` + + 也可以同时执行VACUUM ANALYZE命令进行查询优化。 + + ```sql + postgres=# VACUUM ANALYZE customer; + ``` + + ```sql + VACUUM + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** VACUUM和ANALYZE会导致I/O流量的大幅增加,这可能会影响其他活动会话的性能。因此,建议通过"vacuum_cost_delay"参数设置《开发者指南》中"GUC参数说明 > 资源消耗 > 基于开销的清理延迟"。 + +3. 删除表。 + + ```sql + postgres=# DROP TABLE customer; + postgres=# DROP TABLE customer_par; + postgres=# DROP TABLE part; + ``` + + 当结果显示为如下信息,则表示删除成功。 + + ```sql + DROP TABLE + ``` + +**维护建议** + +- 定期对部分大表做VACUUM FULL,在性能下降后为全库做VACUUM FULL,目前暂定每月做一次VACUUM FULL。 +- 定期对系统表做VACUUM FULL,主要是PG_ATTRIBUTE。 +- 启用系统自动清理线程(AUTOVACUUM)自动执行VACUUM和ANALYZE,回收被标识为删除状态的记录空间,并更新表的统计数据。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/9-routinely-recreating-an-index.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/9-routinely-recreating-an-index.md new file mode 100644 index 00000000..42e0e626 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/9-routinely-recreating-an-index.md @@ -0,0 +1,72 @@ +--- +title: 日常运维 +summary: 日常运维 +author: Zhang Cuiping +date: 2021-03-04 +--- + +# 例行重建索引 + +## 背景信息 + +数据库经过多次删除操作后,索引页面上的索引键将被删除,造成索引膨胀。例行重建索引,可有效的提高查询效率。 + +数据库支持的索引类型为B-tree索引,例行重建索引可有效的提高查询效率。 + +- 如果数据发生大量删除后,索引页面上的索引键将被删除,导致索引页面数量的减少,造成索引膨胀。重建索引可回收浪费的空间。 +- 新建的索引中逻辑结构相邻的页面,通常在物理结构中也是相邻的,所以一个新建的索引比更新了多次的索引访问速度要快。 + +
+ +## 重建索引 + +重建索引有以下两种方式: + +- 先运行DROP INDEX语句删除索引,再运行CREATE INDEX语句创建索引。 + + 在删除索引过程中,会在父表上增加一个短暂的排他锁,阻止相关读写操作。在创建索引过程中,会锁住写操作但是不会锁住读操作,此时读操作只能使用顺序扫描。 + +- 使用REINDEX语句重建索引。 + + - 使用REINDEX TABLE语句重建索引,会在重建过程中增加排他锁,阻止相关读写操作。 + - 使用REINDEX INTERNAL TABLE语句重建desc表(包括列存表的cudesc表)的索引,会在重建过程中增加排他锁,阻止相关读写操作。 + +
+ +## 操作步骤 + +假定在导入表"areaS"上的"area_id"字段上存在普通索引"areaS_idx"。重建索引有以下两种方式: + +- 先删除索引(DROP INDEX),再创建索引(CREATE INDEX) + + 1. 删除索引。 + + ```sql + MogDB=# DROP INDEX areaS_idx; + DROP INDEX + ``` + + 2. 创建索引。 + + ```sql + MogDB=# CREATE INDEX areaS_idx ON areaS (area_id); + CREATE INDEX + ``` + +- 使用REINDEX重建索引。 + + - 使用REINDEX TABLE语句重建索引。 + + ```sql + MogDB=# REINDEX TABLE areaS; + REINDEX + ``` + + - 使用REINDEX INTERNAL TABLE重建desc表(包括列存表的cudesc表)的索引。 + + ```sql + MogDB=# REINDEX INTERNAL TABLE areaS; + REINDEX + ``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** 在重建索引前,用户可以通过临时增大maintenance_work_mem和psort_work_mem的取值来加快索引的重建。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/slow-sql-diagnosis.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/slow-sql-diagnosis.md new file mode 100644 index 00000000..0c81719e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/slow-sql-diagnosis.md @@ -0,0 +1,29 @@ +--- +title: 慢SQL诊断 +summary: 慢SQL诊断 +author: Guo Huan +date: 2022-04-13 +--- + +# 慢SQL诊断 + +## 背景信息 + +在SQL语句执行性能不符合预期时,可以查看SQL语句执行信息,便于事后分析SQL语句执行时的行为,从而诊断SQL语句执行出现的相关问题。 + +## 前提条件 + +- 数据库实例运行正常。 + +- 查询SQL语句信息,需要正确设置GUC参数track_stmt_stat_level。 + +- 只能用系统管理员和监控管理员权限进行操作。 + + ``` + 执行命令查看数据库实例中SQL语句执行信息 + gsql> select * from dbe_perf.get_global_full_sql_by_timestamp(start_timestamp, end_timestamp); + 执行命令查看数据库实例中慢SQL语句执行信息 + gsql> select * from dbe_perf.get_global_slow_sql_by_timestamp(start_timestamp, end_timestamp); + 查看当前节点SQL语句执行信息 + gsql> select * from statement_history; + ``` diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/using-the-gsql-client-for-connection.md b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/using-the-gsql-client-for-connection.md new file mode 100644 index 00000000..aa48c19a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/routine-maintenance/using-the-gsql-client-for-connection.md @@ -0,0 +1,212 @@ +--- +title: gsql客户端连接 +summary: gsql客户端连接 +author: Guo Huan +date: 2021-12-2 +--- + +# gsql客户端连接 + +## 确认连接信息 + +客户端工具通过数据库主节点连接数据库。因此连接前,需获取数据库主节点所在服务器的IP地址及数据库主节点的端口号信息。 + +1. 以操作系统用户omm登录数据库主节点。 + +2. 使用"gs_om -t status --detail"命令查询MogDB各实例情况。 + + ```bash + gs_om -t status --detail + + [ Datanode State ] + + node node_ip instance state + --------------------------------------------------------------------------------- + 1 mogdb-kernel-0005 172.16.0.176 6001 /mogdb/data/db1 P Primary Normal + ``` + + 如上部署了数据库主节点实例的服务器IP地址为172.16.0.176。数据库主节点数据路径为"/mogdb/data/db1"。 + +3. 确认数据库主节点的端口号。 + + 在步骤2查到的数据库主节点数据路径下的postgresql.conf文件中查看端口号信息。示例如下: + + ```bash + cat /mogdb/data/db1/postgresql.conf | grep port + + port = 26000 # (change requires restart) + #comm_sctp_port = 1024 # Assigned by installation (change requires restart) + #comm_control_port = 10001 # Assigned by installation (change requires restart) + # supported by the operating system: + # e.g. 'localhost=10.145.130.2 localport=12211 remotehost=10.145.130.3 remoteport=12212, localhost=10.145.133.2 localport=12213 remotehost=10.145.133.3 remoteport=12214' + # e.g. 'localhost=10.145.130.2 localport=12311 remotehost=10.145.130.4 remoteport=12312, localhost=10.145.133.2 localport=12313 remotehost=10.145.133.4 remoteport=12314' + # %r = remote host and port + alarm_report_interval = 10 + support_extended_features=true + ``` + + 第一行中的26000为数据库主节点的端口号。 + +
+ +## 安装gsql客户端 + +在客户端机器上,上传客户端工具包并配置gsql的执行环境变量。 + +1. 以任意用户登录客户端机器。 + +2. 创建"/opt/mogdb/tools"目录。 + + ```bash + mkdir /opt/mogdb/tools + ``` + +3. 获取软件安装包中的"MogDB-x.x.x-openEuler-64bit-tools.tar.gz"上传到"/opt/mogdb/tools"路径下。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: + > + > - 软件包相对位置为安装时所放位置,根据实际情况填写。 + > - 不同的操作系统,工具包文件名称会有差异。请根据实际的操作系统类型选择对应的工具包。 + +4. 解压文件。 + + ```bash + cd /opt/mogdb/tools + tar -zxvf MogDB-x.x.x-openEuler-64bit-tools.tar.gz + ``` + +5. 设置环境变量。 + + 打开"~/.bashrc"文件。 + + ```bash + vi ~/.bashrc + ``` + + 在其中输入如下内容后,使用":wq!"命令保存并退出。 + + ```bash + export PATH=/opt/mogdb/tools/bin:$PATH + export LD_LIBRARY_PATH=/opt/mogdb/tools/lib:$LD_LIBRARY_PATH + ``` + +6. 使环境变量配置生效。 + + ```bash + source ~/.bashrc + ``` + +
+ +## 使用gsql连接数据库 + +
+ +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 缺省情况下,客户端连接数据库后处于空闲状态时会根据参数session_timeout的默认值自动断开连接。如果要关闭超时设置,设置参数session_timeout为0即可。 + +
+ +### 本地连接数据库 + +1. 以操作系统用户omm登录数据库服务器。 + +2. 连接数据库。 + + 数据库安装完成后,默认生成名称为postgres的数据库。第一次连接数据库时可以连接到此数据库。 + + 执行如下命令连接数据库。 + + ```bash + gsql -d postgres -p 26000 + ``` + + 其中postgres为需要连接的数据库名称,26000为数据库主节点的端口号。请根据实际情况替换。 + + 连接成功后,系统显示类似如下信息: + + ```sql + gsql ((MogDB x.x.x build 56189e20) compiled at 2022-01-07 18:47:53 commit 0 last mr ) + Non-SSL connection (SSL connection is recommended when requiring high-security) + Type "help" for help. + + postgres=# + ``` + + omm用户是管理员用户,因此系统显示"postgres=#"。若使用普通用户身份登录和连接数据库,系统显示"postgres=>"。 + + "Non-SSL connection"表示未使用SSL方式连接数据库。如果需要高安全性时,请使用SSL连接。 + +3. 退出数据库。 + + ```sql + postgres=# \q + ``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 使用omm用户在本地连接数据库,无需输入密码,这是由于在pg_hba.conf文件中默认设置了本机允许trust方式连接。 +> - 更多关于客户端认证方式的信息,请参见[客户端接入认证](../../security-guide/security/1-client-access-authentication.md)章节。 + +
+ +## 远程连接数据库 + +
+ +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 由于安全性限制,数据库初始用户omm无法进行远程连接。 + +
+ +### 通过gs_guc配置白名单(更新pg_hba.conf文件) + +1. 以操作系统用户omm登录数据库主节点。 + +2. 配置客户端认证方式,允许客户端以"jack"用户连接到本机,远程连接禁止使用"omm"用户(即数据库初始化用户)。 + + 例如,下面示例中配置允许IP地址为172.16.0.245的客户端访问本机。 + + ```bash + gs_guc set -N all -I all -h "host all jack 172.16.0.245/24 sha256" + ``` + + **注意:** + + - 使用"jack"用户前,需先本地连接数据库,并在数据库中使用如下语句建立"jack"用户: + + ```sql + postgres=# CREATE USER jack PASSWORD 'Test@123'; + ``` + + - -N all表示MogDB的所有主机。 + + - -I all表示主机的所有实例。 + + - -h表示指定需要在"pg_hba.conf"增加的语句。 + + - all表示允许客户端连接到任意的数据库。 + + - jack表示连接数据库的用户。 + + - 172.16.0.245/24表示只允许IP地址为172.16.0.245的主机连接。此处的IP地址不能为MogDB内的IP,在使用过程中,请根据用户的网络进行配置修改。24表示子网掩码为1的位数,即255.255.255.0。 + + - sha256表示连接时jack用户的密码使用sha256算法加密。 + + 这条命令在数据库主节点实例对应的"pg_hba.conf"文件中添加了一条规则,用于对连接数据库主节点的客户端进行鉴定。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: + > + > + 更多关于客户端认证方式的信息,请参见[客户端接入认证](../../security-guide/security/1-client-access-authentication.md)章节。 + +3. 连接数据库。 + + 数据库安装完成后,默认生成名称为postgres的数据库。第一次连接数据库时可以连接到此数据库。 + + ```bash + gsql -d postgres -h 172.16.0.176 -U jack -p 26000 -W Test@123 + ``` + + postgres为需要连接的数据库名称,172.16.0.176为数据库主节点所在的服务器IP地址,jack为连接数据库的用户,26000为数据库主节点的端口号,Test@123为连接数据库用户jack的密码。 diff --git a/product/zh/docs-mogdb/v3.1/administrator-guide/upgrade-guide.md b/product/zh/docs-mogdb/v3.1/administrator-guide/upgrade-guide.md new file mode 100644 index 00000000..8399dd8a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/administrator-guide/upgrade-guide.md @@ -0,0 +1,360 @@ +--- +title: 升级指南 +summary: 升级指南 +author: Zhang Cuiping +date: 2021-09-27 +--- + +# 升级指南 + +## 概述 + +本文档详细的描述了版本升级、回滚流程、以及具体的操作指导,同时提供了常见的问题解答及故障处理方法。 + +## 读者对象 + +本文档主要适用于升级的操作人员。操作人员必须具备以下经验和技能: + +- 熟悉当前网络的组网和相关网元的版本信息。 +- 有该设备维护经验,熟悉设备的操作维护方式。 + +## 升级方案 + +本节为指导用户选择升级方式。 + +用户根据MogDB提供的新特性和数据库现状,确定是否对现有系统进行升级。 + +当前支持的升级模式为就地升级和灰度升级。升级方式的策略又分为大版本升级和小版本升级。 + +用户挑选升级方式后,系统会自动判断并选择合适的升级策略。 + +* 就地升级: 升级期间需停止业务进行,一次性升级所有节点。 + +* 灰度升级: 灰度升级支持全业务操作,也是一次性升级所有节点。(MogDB1.1.0之后的版本支持该功能) + +## 升级前的版本要求(升级路径) + +MogDB升级版本要求如[表1](#biaoyi)所示。 + +**表 1** 升级前的版本要求(升级路径) + +| 版本 | 升级说明 | +| --------- | ---------------------------------------- | +| MogDB 2.0 | 需要先升级到MogDB 2.1,再升级到MogDB 3.0 | +| MogDB 2.1 | 可以升级到MogDB 3.0 | + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**:升级前版本,可以通过执行如下工具查看。 +> +> ```bash +> gsql -V | --version +> ``` + +## 升级影响和升级约束 + +升级过程需要注意以下事项。 + +- 升级操作不能和扩容、缩容同时执行。 +- 不支持虚拟IP。 +- 升级过程中,不允许对wal_level,max_connections,max_prepared_transactions,max_locks_per_transaction这四个GUC参数的值进行修改。如果修改,会导致回滚后实例启动异常。 +- 建议在数据库系统空闲情况下进行升级,尽量避开业务繁忙的时间段(可按照经验判断,如节假日等)。 +- 升级前尽可能保证数据库正常。可以通过gs_om -t status查询,查询结果的cluster_state为Normal代表数据库正常。 +- 升级前保证数据库互信正常,可以在任意节点上,通过ssh hostname命令,连接另外一个节点进行验证。如果各机器间互连不用输入密码,说明互信正常(通常数据库状态正常时,互信一般都是正常的)。 +- 升级前后,数据库的部署方式(配置文件)不能发生变化。升级前会对部署方式进行校验,如果改变,会报错。 +- 升级前要保证操作系统处于健康状态,通过gs_checkos工具可以完成操作系统状态检查。 +- 就地升级需要停止业务,灰度升级支持全业务操作。 +- 数据库运行正常且主DN的数据完全同步到备DN。 +- 升级过程中不允许打开kerberos开关。 +- 请不要修改安装包中解压出来的version.cfg文件。 +- 如果升级过程中出现异常导致升级失败,需用户手动回滚,并且必须回滚成功后才能进行下一次升级。 +- 如果升级回滚成功后,再次升级成功,未提交阶段设置的GUC参数将失效。 +- 执行升级的过程中请不要手动设置GUC参数。 +- 灰度升级中,升级的时候都会产生不超过10s的业务中断 +- 升级过程中,必须保持内核版本与om版本一致才可执行om操作。这里的一致是指,内核代码和om代码都来自同一个软件包。如果执行了升级包的前置脚本却没有升级,或者升级回滚后没有执行基线包的前置脚本,就会造成内核代码和om代码的不一致。 +- 升级过程中如果系统表新增了字段,升级后通过`\d`命令将查看不到这些新增的字段。此时通过`select`命令可以查到这些新增的字段。 +- 升级需要guc参数enable_stream_replication=on,该参数为off时不允许升级。 +- 灰度升级中,业务并发要小于200并发读加200并发写的情况。 +- 若在MogDB 2.0之前的版本中使用了MOT表,则不支持升级到MogDB 2.0版本。 + +## 升级流程 + +本章介绍升级到该版本的主要升级过程。 + +**图 1** 升级流程图 + +![12](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/upgrade-guide-1.png) + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明**:本文档中描述的时间仅供参考,实际操作时间以现场情况为准。 + +**表 2** 升级流程执行效率估计 + +
步骤 建议起始时间 耗时(天/小时/分钟) 业务中断时长 备注
升级前准备与检查 升级操作前一天 约2~3小时。 对业务无影响。 升级前检查和备份数据、校验软件包等操作。
升级操作 业务空闲期 耗时主要集中在数据库的启动和停止以及每个database的系统表修改处。升级操作耗时一般不会超过30分钟。 与操作时长一致,一般不会超过30分钟。 依据指导书开始升级。
升级验证 业务空闲期 约30分钟。 与操作时长一致,约30分钟。 -
提交升级 业务空闲期 提交升级耗时一般不超过10分钟。 与操作时长一致,一般不超过10分钟。 -
升级版本回滚 业务空闲期 版本回滚耗时一般不会超过30分钟。 与操作时长一致,一般不会超过30分钟。 -
+ +## 升级前准备与检查 + +### 升级前准备与检查清单 + +**表 3** 升级前准备清单 + +
序号 升级准备项目项目 准备内容 建议起始时间 耗时(天/小时/分钟)
1 收集节点信息 收集到数据库涉及节点的名称、IP地址,root、omm用户密码等环境信息。 升级前一天 1小时
2 设置root用户远程登录 设置配置文件,允许root用户远程登录。 升级前一天 2小时
3 备份数据 参考《管理指南》中的“备份与恢复”章节进行。 升级前一天 备份数据量和方案不同,耗时也不同
4 获取并校验升级包 获取升级软件包,进行完整性校验。 升级前一天 0.5小时
5 健康检查 使用gs_checkos工具完成操作系统状态检查。 升级前一天 0.5小时
6 检查数据库节点磁盘使用率 使用df命令查看磁盘使用率。 升级前一天 0.5小时
7 检查数据库状态 使用gs_om工具完成数据库状态检查。 升级前一天 0.5小时
+ +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明**:“耗时”依不同环境(包括现场数据量、服务器性能等原因)会存在一定差异。 + +### 收集节点信息 + +联系数据库系统管理员,获取数据库涉及节点的节点名称、节点IP地址。节点的root、omm用户密码等环境信息。 + +**表 4** 节点信息 + + + + + + + + + + + + + + + + + + +
序号 节点名称 节点IP +root用户密码 omm用户密码 备注
1 +- +- - - -
+ +### 备份数据 + +升级一旦失败,有可能会影响到业务的正常开展。提前备份数据,就可以在风险发生后,尽快的恢复业务。 + +请参考《管理指南》中的[备份与恢复](../administrator-guide/br/1-1-br.md)章节,完成数据的备份。 + +### 获取升级包 + +访问[MogDB官网下载页面](https://www.mogdb.io/downloads/mogdb)获取想要升级的升级包。 + +### 健康检查 + +通过gs_checkos工具可以完成操作系统状态检查。 + +**前提条件** + +- 当前的硬件和网络环境正常。 +- 各主机间root互信状态正常。 +- 只能使用root用户执行gs_checkos命令。 + +> **说明:** 该工具不支持独立调用,出于安全考虑,前置安装完成后会自动删除。 + +**操作步骤** + +1. 以root用户身份登录服务器。 + +2. 执行如下命令对服务器的OS参数进行检查。 + + ```shell + gs_checkos -i A + ``` + + 检查服务器的OS参数的目的是为了保证数据库正常通过预安装,并且在安装成功后可以安全高效的运行。 + +#### 检查数据库节点磁盘使用率 + +建议数据库节点磁盘使用率低于80%时再执行升级操作。 + +#### 检查数据库状态 + +本节介绍数据库状态查询的具体操作。 + +**验证步骤** + +1. 以数据库用户(如omm)登录节点,source环境变量。 + + ```shell + su - omm + source /home/omm/.bashrc + ``` + +2. 执行如下命令查看数据库状态。 + + ```shell + gs_om -t status + ``` + +3. 保证数据库状态正常。 + +## 升级操作 + +介绍就地升级和灰度升级的详细操作。 + +**操作步骤** + +1. 以root身份登录节点。 + +2. 创建新包目录。 + + ```shell + mkdir -p /opt/software/mogdb_upgrade + ``` + +3. 将需要更新的新包上传至目录"/opt/software/mogdb_upgrade"并解压。 + +4. 进入安装包解压出的script目录下: + + ```shell + cd /opt/software/mogdb_upgrade/script + ``` + +5. 创建static文件夹,将plugin插件包放到script/static文件夹下。(这一步是必须操作,因为当前版本没有判断用户有没有使用插件,所以在升级脚本中默认数据库安装使用插件,以后的版本中会将插件部分单独拆出来。) + + 例如: + + ```sql + mkdir static + cd static/ + wget https://cdn-mogdb.enmotech.com/mogdb-media/3.0.1/Plugins-3.0.1-CentOS-x86_64.tar.gz + ``` + +6. 在就地升级或灰度升级前执行前置脚本gs_preinstall。 + + ```shell + ./gs_preinstall -U omm -G dbgrp -X /opt/software/mogdb/clusterconfig.xml + ``` + +7. 切换至omm用户。 + + ```shell + su - omm + ``` + +8. 数据库状态正常时,使用如下命令进行就地升级或者灰度升级。 + + 示例一: 使用gs_upgradectl脚本执行就地升级。 + + ```shell + gs_upgradectl -t auto-upgrade -X /opt/software/mogdb/clusterconfig.xml + ``` + + 示例二: 使用gs_upgradectl脚本执行灰度升级。 + + ```shell + gs_upgradectl -t auto-upgrade -X /opt/software/mogdb/clusterconfig.xml --grey + ``` + +## 升级验证 + +本章介绍升级完成后的验证操作。给出验证的用例和详细操作步骤。 + +### 验证项目的检查表 + +**表 5** 验证项目的检查表 + +
序号 验证项目 检查标准 检查结果
1 版本查询 查询升级后版本是否正确 -
2 健康检查 使用gs_checkos工具完成操作系统状态检查。 -
3 数据库状态 使用gs_om工具完成数据库状态检查。 -
+ +### 升级版本查询 + +本节介绍版本查询的具体操作。 + +**验证步骤** + +1. 以数据库用户(如omm)登录节点,source环境变量。 + + ```shell + su - omm + source /home/omm/.bashrc + ``` + +2. 执行如下命令查看所有节点的版本信息。 + + ```shell + gs_ssh -c "gsql -V" + ``` + +### 检查升级数据库状态 + +本节介绍数据库状态查询的具体操作。 + +**验证步骤** + +1. 以数据库用户(如omm)登录节点。 + + ```shell + su - omm + ``` + +2. 执行如下命令查看数据库状态。 + + ```shell + gs_om -t status + ``` + + 查询结果的cluster_state为Normal代表数据库正常。 + +## 提交升级 + +升级完成后,如果验证也没问题。接下来就可以提交升级。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**:一旦提交操作完成,则不能再执行回滚操作。 + +**操作步骤** + +1. 以数据库用户(如omm)登录节点。 + + ```shell + su - omm + ``` + +2. 执行如下命令完成升级提交。 + + ```shell + gs_upgradectl -t commit-upgrade -X /opt/software/mogdb/clusterconfig.xml + ``` + +## 升级版本回滚 + +本章介绍版本回滚方法。 + +**操作步骤** + +1. 以数据库用户(如omm)登录节点。 + + ```shell + su - omm + ``` + +2. 执行如下命令完成版本回滚(回滚内核代码)。回滚完成,如果需要保持内核和om代码的版本一致,可以执行一下旧包的前置命令(参见[执行前置脚本gs_preinstall](#qianzhijiaoben))。 + + ```shell + gs_upgradectl -t auto-rollback -X /opt/software/mogdb/clusterconfig.xml + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明:** 如果数据库异常,需要强制回滚,可以使用如下命令。 + > + > ```shell + > gs_upgradectl -t auto-rollback -X /opt/software/mogdb/clusterconfig.xml --force + > ``` + +3. 查看回滚之后的版本号。 + + ```shell + gs_om -V | --version + ``` + + 如果升级失败,请按照如下方式进行处理: + + a. 排查是否有环境问题。 + + 如磁盘满、网络故障等,或者升级包、升级版本号是否正确。排除问题后,可以尝试重入升级。 + + b. 如果没有发现环境问题,或者重入升级失败,需要收集相关日志,找技术支持工程师定位。 + + 收集日志命令: + + ```shell + gs_collector -begin-time='20200724 00:00' -end-time='20200725 00:00' + ``` + + 如果条件允许,建议保留环境。 diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai-in-db/predictor-ai-query-time-forecasting.md b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai-in-db/predictor-ai-query-time-forecasting.md new file mode 100644 index 00000000..678d7d08 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai-in-db/predictor-ai-query-time-forecasting.md @@ -0,0 +1,48 @@ +--- +title: Predictor:AI查询时间预测 +summary: Predictor:AI查询时间预测 +author: Guo Huan +date: 2022-05-10 +--- + +# Predictor:AI查询时间预测 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +Predictor是基于机器学习且具有在线学习能力的查询时间预测工具。在数据库内核中,通过不断学习数据库内收集的历史执行信息,实现计划的执行时间预测功能。 + +## 客户价值 + +在SQL语句执行之前,根据AI模型预测SQL执行时间。用户基于推测的SQL时间信息,可以发现可能的异常SQL语句,提前进行调优或者调度,以免影响系统运行。 + +## 特性描述 + +AI查询时间预测,依赖于本地查询计划收集。用户需要根据需求在查询执行时,收集实际查询计划(包括计划结构、算子类型、相关数据源、过滤条件等)、各算子节点实际执行时间、优化器估算代价、实际返回行数、优化器估算行数、并行数等信息。这些记录将保存在数据表中,并进行持久化管理包括定期进行数据失效清理。 + +数据库内核在自动收集历史数据后,由管理员进行编码,然后通过CURL接口向python端发送请求以配置模型、发送数据、触发训练。训练过程中可以通过调用tensorboard接口监控训练过程。模型最终返回各项目预测准确率,并保存最终模型。数据库根据aiEngine端返回结果更新模型信息相关系统表。 + +执行explain (analyze on, predictor ) SELECT …”时且模型收敛时触发,数据库根据Plan进行编码判断是否符合当前模型。如果符合模型,先向python端发送加载模型请求(模型训练完成后只需加载一次),模型加载后对计划编码文件进行推理并返回各节点预测结果。 + +## 特性增强 + +无。 + +## 特性约束 + +- 数据库系统处于正常状态,用户通过身份验证成功登陆数据库访问拥有权限的数据。 +- 用户执行的SQL语法正确无报错。 +- 用户执行的SQL不会导致数据库异常等。 +- 历史性能数据窗口内集群并发量稳定,集群规模、表结构、表数量不变,数据量无突变,涉及查询性能的guc参数不变。如果上述条件被破坏,模型失效,需要对所有历史性能数据进行失效并重新进行数据收集和重新训练模型。 +- 加载模型时,原模型的结构、参数和训练信息等保存完整。若原模型信息丢失,模型无法正常加载,需要重新训练。 +- 历史性能数据正常收集和编码,正常解析编码数据不报错。 +- 用户通过预提供的安装脚本或者自行安装Python\==3.6.4,configparser\==3.8.1,Flask\==0.12.2,Keras\==2.2.4,numpy\==1.16.4,scikit-learn\==0.19.1,pandas\==0.25.1, tensorboard\==1.14.0,tensorflow-gpu\==1.14.0或tensorflow\==1.14.0。 +- 用户环境中已经安装了OpenSSL,使用脚本或者按照使用说明生成了证书。 +- 目前跨database namespace的模型同步需要管理员用户手动执行,不支持自动同步。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/1-database-metric-collection-forecast-and-exception-detection.md b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/1-database-metric-collection-forecast-and-exception-detection.md new file mode 100644 index 00000000..80f233ac --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/1-database-metric-collection-forecast-and-exception-detection.md @@ -0,0 +1,41 @@ +--- +title: 数据库指标采集、预测与异常监控 +summary: 数据库指标采集、预测与异常监控 +author: Guo Huan +date: 2022-05-10 +--- + +# 数据库指标采集、预测与异常监控 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +本特性是MogDB集成的、可以用于数据库指标采集、预测以及异常监控与诊断的AI工具,是DBMind套间中的一个组件。当前通过兼容Prometheus平台来采集数据库系统的指标,提供Prometheus exporter用于采集和加工数据库监控指标。通过监控指标时序数据,可以用来预测未来负载走向,诊断问题等。 + +## 客户价值 + +- 极大简化运维人员工作,释放大量劳动力,为公司节省成本。 +- 用户可以通过指标采集、监控和预测功能提前感知问题,从而防止数据库发生意外,导致更大的损失。 + +## 特性描述 + +Prometheus是业内非常流行的开源监控系统,同时本身也是一款时序数据库。Prometheus的采集端称之为exporter,用来收集被监控模块的指标项。为了与Prometheus平台完成对接,DBMind分别实现了两款exporter,分别是用来采集数据库指标的openGauss-exporter,以及对采集到的指标进行二次加工的reprocessing-exporter。 + +本特性支持对采集到的指标进行预测,用户可通过修改配置文件来指定需要进行预测的关键系统指标(KPI),进而便于用户发现指标的走势,及时进行对应的运维操作。如预测内存使用率可以发现内存泄漏、预测磁盘使用情况可以在合适的时候扩容。 + +## 特性增强 + +在 MogDB 3.0.0版本中,进行了大幅度改进,兼容Prometheus平台,实现两个exporter用于对接Prometheus. + +## 特性约束 + +- 数据库状态正常,并且用户已将数据目录写入环境变量; +- Python版本要求3.6及以上; +- 配置Prometheus监控平台,并启动本服务,以便监控数据可被收集。 + +## 依赖关系 + +Prometheus \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/2-root-cause-analysis-for-slow-sql-statements.md b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/2-root-cause-analysis-for-slow-sql-statements.md new file mode 100644 index 00000000..f70f1024 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/2-root-cause-analysis-for-slow-sql-statements.md @@ -0,0 +1,38 @@ +--- +title: 慢SQL根因分析 +summary: 慢SQL根因分析 +author: Guo Huan +date: 2022-05-10 +--- + +# 慢SQL根因分析 + +## 可获得性 + +本特性自MogDB 3.0.0开始引入。 + +## 特性简介 + +慢SQL一直是数据运维中的痛点问题,如何有效诊断慢SQL根因是当前一大难题,工具结合MogDB自身特点融合了现网DBA慢SQL诊断经验,该工具可以支持慢SQL根因15+,能同时按照可能性大小输出多个根因并提供针对性的建议。 + +## 客户价值 + +为客户提供快速可靠的慢SQL发现及根因分析功能,极大简化了运维人员的工作。 + +## 特性描述 + +基于Prometheus数据采集方案,收集慢SQL根因分析需要的数据,包括系统资源信息(cpu usage、memory usage、IO)、负载信息(QPS)、大进程信息(包括外部大进程和数据库定时任务)、慢SQL文本信息、慢SQL开始执行时间和结束执行时间、慢SQL执行计划,临时文件信息等信息,而后,本功能根据AI算法计算最匹配的慢SQL根因,并给出对应的建议和置信度。 + +## 特性增强 + +无 + +## 特性约束 + +- 数据库状态正常、客户端能够正常连接; +- 具备Python3.6+的环境; +- 其中慢SQL的信息通过WDR报告获取,数据库WDR报告中会标记SQL是否是慢SQL,其相关GUC参数track_stmt_stat_level默认打开,否则需要用户手动打开,一般设置为track_stmt_stat_level=’off, L0’,更高级别对性能会有一定的影响。数据采集部分由Prometheus方案实现,故需要用户配置Prometheus数据采集平台,本功能只专注于算法并从Prometheus中获取指标的序列信息; + +## 依赖关系 + +无 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/3-index-recommendation.md b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/3-index-recommendation.md new file mode 100644 index 00000000..7ad8e2d3 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/3-index-recommendation.md @@ -0,0 +1,40 @@ +--- +title: 索引推荐 +summary: 索引推荐 +author: Guo Huan +date: 2022-05-10 +--- + +# 索引推荐 + +## 可获得性 + +本特性自MogDB 1.1.0开始引入。 + +## 特性简介 + +本功能是一个覆盖多种任务级别和使用场景的数据库智能索引推荐工具,其具备单Query索引推荐功能、虚拟索引功能、workload级别索引推荐功能,可以为用户提供可靠的索引建议。 + +## 客户价值 + +为客户提供快速可靠的索引推荐功能,极大简化了运维人员的工作。 + +## 特性描述 + +单query索引推荐功能支持用户在数据库中直接进行操作,本功能基于查询语句的语义信息和数据库的统计信息,对用户输入的单条查询语句生成推荐的索引;虚拟索引功能支持用户在数据库中直接进行操作,本功能将模拟真实索引的建立,避免真实索引创建所需的时间和空间开销,用户基于虚拟索引,可通过优化器评估该索引对指定查询语句的代价影响;对于workload级别的索引推荐,用户可通过运行数据库外的脚本使用此功能,本功能将包含有多条DML语句的workload作为输入,最终生成一批可对整体workload的执行表现进行优化的索引。 + +## 特性增强 + +无 + +## 特性约束 + +数据库状态正常、客户端能够正常连接。 + +当前执行用户下安装有gsql工具,该工具路径已被加入到PATH环境变量中。 + +具备Python3.6+的环境。 + +## 依赖关系 + +无 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/4-parameter-tuning-and-diagnosis.md b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/4-parameter-tuning-and-diagnosis.md new file mode 100644 index 00000000..1c2defc6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/4-parameter-tuning-and-diagnosis.md @@ -0,0 +1,46 @@ +--- +title: 参数调优与诊断 +summary: 参数调优与诊断 +author: Guo Huan +date: 2022-05-10 +--- + +# 参数调优与诊断 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入 + +## 特性简介 + +本功能是一款数据库集成的参数调优工具,通过结合深度强化学习和全局搜索算法等AI技术,实现在无需人工干预的情况下,获取最佳数据库参数配置。本功能不强制与数据库环境部署到一起,支持独立部署,脱离数据库安装环境独立运行。 + +## 客户价值 + +该工具可以在任意场景下,快速给出当前负载的调参配置,减少DBA的人工干预,提升运维效果,满足客户期望。 + +## 特性描述 + +调优程序包含三种运行模式,分别是: + +- recommend: 通过用户指定的用户名等信息登录到数据库环境中,获取当前正在运行的workload特征信息,根据上述特征信息生成参数推荐报告。报告当前数据库中不合理的参数配置和潜在风险等;输出根据当前正在运行的workload行为和特征;输出推荐的参数配置。**该模式是秒级的,不涉及数据库的重启操作,其他模式可能需要反复重启数据库**。 +- train: 通过用户提供的benchmark信息,不断地进行参数修改和benchmark的执行。通过反复的迭代过程,训练强化学习模型,以便用户在后面通过tune模式加载该模型进行调优。 +- tune: 使用优化算法进行数据库参数的调优,当前支持两大类算法,一种是深度强化学习,另一种是全局搜索算法(全局优化算法)。深度强化学习模式要求先运行train模式,生成训练后的调优模型,而使用全局搜索算法则不需要提前进行训练,可以直接进行搜索调优。 + +## 特性增强 + +无 + +## 特性约束 + +- 数据库状态正常、客户端能够正常连接、且要求数据库内导入数据,以便调优程序可以执行benchmark测试调优效果。 +- 使用本工具需要指定登录到数据库的用户身份,要求该登录到数据库上的用户具有足够的权限,以便可以获得充足的数据库状态信息。 +- 使用登录到数据库宿主机上的Linux用户,需要将$**GAUSSHOME/bin**添加到PATH环境变量中,即能够直接运行gsql、gs_guc、gs_ctl等数据库运维工具。 +- Python版本建议为Python3.6及以上,且运行环境中已经安装相应依赖,并能够正常启动调优程序。您可以独立安装一个python3.6+的环境,无需设置到全局环境变量中。不建议使用root用户权限安装本工具,如果以root身份安装本完毕工具,使用其他用户身份运行本工具时,需要确保配置文件有读取权限。 +- 本工具支持以三种模式运行,其中tune和train模式要求用户配置好benchmark运行环境,并导入数据,本工具将会通过迭代运行benchmark来判断修改后的参数是否有性能提升。 +- recommend模式建议在数据库正在执行workload的过程中执行,以便获得更准确的实时workload信息。 +- 本工具默认带有TPC-C、TPC-H、TPC-DS以及sysbench的benchmark运行脚本样例,如果用户使用上述benchmark对数据库系统进行压力测试,则可以对上述配置文件进行适度修改或配置。如果需要适配用户自己的业务场景,需要您参照benchmark目录中的template.py文件编写驱动您自定义benchmark的脚本文件。 + +## 依赖关系 + +无 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/5-slow-sql-statement-discovery.md b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/5-slow-sql-statement-discovery.md new file mode 100644 index 00000000..6bc1a027 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/ai4db-autonomous-database-o-m/5-slow-sql-statement-discovery.md @@ -0,0 +1,39 @@ +--- +title: 慢SQL发现 +summary: 慢SQL发现 +author: Guo Huan +date: 2022-05-10 +--- + +# 慢SQL发现 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +本功能是一个SQL语句执行时间预测工具,通过模板化方法,实现在不获取SQL语句执行计划的前提下,依据语句逻辑相似度与历史执行记录,预测SQL语句的执行时间。 + +## 客户价值 + +- 工具不需要用户提供SQL执行计划,对数据库性能不会有任何影响。 +- 不同于业内其他算法只局限于OLAP或者OLTP,本工具场景更加广泛。 + +## 特性描述 + +SQLdiag着眼于数据库的历史SQL语句,通过对历史SQL语句的执行表现进行总结归纳,将之再用于推断新的未知业务上。由于短时间内数据库SQL语句执行时长不会有太大的差距,SQLdiag可以从历史数据中检测出与已执行SQL语句相似的语句结果集,并基于SQL向量化技术和模板化方法预测SQL语句执行时长。 + +## 特性增强 + +无 + +## 特性约束 + +- 需要保证用户提供的历史日志及待预测负载的格式符合要求,可以使用数据库GUC参数开启收集,也可以通过监控工具采集。 +- 为保证预测准确率,用户提供的历史语句日志应尽可能全面并具有代表性。 +- 按照要求配置python环境。 + +## 依赖关系 + +无 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/db4ai-database-driven-ai.md b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/db4ai-database-driven-ai.md new file mode 100644 index 00000000..f5b56e22 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/ai-capabilities/db4ai-database-driven-ai.md @@ -0,0 +1,39 @@ +--- +title: DB4AI:数据库驱动AI +summary: DB4AI:数据库驱动AI +author: Guo Huan +date: 2022-05-10 +--- + +# DB4AI:数据库驱动AI + +## 可获得性 + +本特性自MogDB 2.1.0版本开始引入。 + +## 特性简介 + +DB4AI是指利用数据库的能力驱动AI任务,实现数据存储、技术栈的同构。通过在数据库内集成AI算法,令MogDB具备数据库原生AI计算引擎、模型管理、AI算子、AI原生执行计划的能力,为用户提供普惠AI技术。不同于传统的AI建模流程,DB4AI“一站式”建模可以解决数据在各平台的反复流转问题,同时简化开发流程,并可通过数据库规划出最优执行路径,让开发者更专注于具体业务和模型的调优上,具备同类产品不具备的易用性与性能优势。 + +## 客户价值 + +- 通过本功能,用户无需手动编写AI模型代码,直接通过开箱即用的SQL语句即可执行机器学习模型的训练和预测,学习和使用成本极低; +- 避免数据碎片化存储和反复搬迁导致的额外开销; +- 更高的执行效率,本功能的AI模型训练效率极高,相比用户自行手动训练模型有数倍性能收益; +- 更严密的安全防护,从而避免训练AI模型导致数据泄露。 + +## 特性描述 + +MogDB的原生DB4AI能力,通过引入原生AI算子,简化操作流程,充分利用数据库优化器、执行器的优化与执行能力,获得高性能的数据库内模型训练能力。更简化的模型训练与预测流程、更高的性能表现,让开发者在更短时间内能更专注于模型的调优与数据分析上,而避免了碎片化的技术栈与冗余的代码实现。 + +## 特性增强 + +在MogDB 3.0.0 版本中支持更多算法。 + +## 特性约束 + +- 数据库状态正常 + +## 依赖关系 + +无 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/1-standard-sql.md b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/1-standard-sql.md new file mode 100644 index 00000000..2ddcd1cf --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/1-standard-sql.md @@ -0,0 +1,38 @@ +--- +title: 支持标准SQL +summary: 支持标准SQL +author: Guo Huan +date: 2022-05-07 +--- + +# 支持标准SQL + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +SQL是用于访问和处理数据库的标准计算机语言。SQL标准的定义分成核心特性以及可选特性,绝大部分的数据库都没有100%支撑SQL标准。 + +MogDB数据库支持SQL:2011大部分的核心特性,同时还支持部分的可选特性,为使用者提供统一的SQL界面。 + +## 客户价值 + +标准SQL的引入为所有的数据库厂商提供统一的SQL界面,减少使用者的学习成本和应用程序的迁移代价。 + +## 特性描述 + +具体的特性列表请参见《参考指南》中“SQL语法”章节。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/2-standard-development-interfaces.md b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/2-standard-development-interfaces.md new file mode 100644 index 00000000..28d6e70c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/2-standard-development-interfaces.md @@ -0,0 +1,36 @@ +--- +title: 支持标准开发接口 +summary: 支持标准开发接口 +author: Guo Huan +date: 2022-05-07 +--- + +# 支持标准开发接口 + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +支持ODBC 3.5及JDBC 4.0标准接口。 + +## 客户价值 + +提供业界标准的ODBC及JDBC接口,保证用户业务快速迁移至MogDB。 + +## 特性描述 + +目前支持标准的ODBC 3.5及JDBC 4.0接口,其中ODBC支持SUSE、Win32、Win64平台,JDBC无平台差异。 + +## 特性增强 + +增加JDBC对接第三方日志框架功能。JDBC对接第三方日志框架功能可满足用户对日志管控的需求。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/3-postgresql-api-compatibility.md b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/3-postgresql-api-compatibility.md new file mode 100644 index 00000000..479479d6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/3-postgresql-api-compatibility.md @@ -0,0 +1,36 @@ +--- +title: PG接口兼容 +summary: PG接口兼容 +author: Guo Huan +date: 2022-05-07 +--- + +# PG接口兼容 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +兼容PSQL客户端,兼容PostgreSQL标准接口。 + +## 客户价值 + +兼容PSQL客户端,兼容PostgreSQL标准接口,能够与PG生态工具无缝对接。 + +## 特性描述 + +兼容PSQL客户端,兼容PostgreSQL标准接口。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/4-pl-java.md b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/4-pl-java.md new file mode 100644 index 00000000..6f591953 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/4-pl-java.md @@ -0,0 +1,66 @@ +--- +title: 支持PL/Java +summary: 支持PL/Java +author: Guo Huan +date: 2022-05-07 +--- + +# 支持PL/Java + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +支持java UDF。 + +## 客户价值 + +提供多种函数的开发环境。 + +## 特性描述 + +使用MogDB数据库的PL/Java函数,用户可以使用自己喜欢的Java IDE编写Java方法,并将包含这些方法的jar文件安装到MogDB数据库中,然后使用该方法。MogDB PL/Java基于开源tada PL/Java 1.5.2开发,PL/Java所使用的JDK版本为Huawei JDK V100R001C00SPC190B003-b09。 + +## 特性增强 + +无。 + +## 特性约束 + +- Java UDF可以实现一些较为简单的java计算,强烈建议不要在Java UDF中封装业务。 + +- 强烈建议不要在Java函数中使用任何方式连接数据库,包括但不限于JDBC。 + +- 建议用户使用Huawei JDK V100R001C00SPC190B003-b09编译Java方法和jar文件。 + +- 暂不支持的数据类型:除表1提及之外的数据类型,包括自定义类型,复杂数据类型(Java Array类及派生类)。 + +- 暂不支持UDAF、UDTF。 + + **表 1** PL/Java默认数据类型映射关系 + + | MogDB | **Java** | + | :---------- | :------------------------------------------------- | + | BOOLEAN | boolean | + | “char” | byte | + | bytea | byte[] | + | SMALLINT | short | + | INTEGER | int | + | BIGINT | long | + | FLOAT4 | float | + | FLOAT8 | double | + | CHAR | java.lang.String | + | VARCHAR | java.lang.String | + | TEXT | java.lang.String | + | name | java.lang.String | + | DATE | java.sql.Timestamp | + | TIME | java.sql.Time (stored value treated as local time) | + | TIMETZ | java.sql.Time | + | TIMESTAMP | java.sql.Timestamp | + | TIMESTAMPTZ | java.sql.Timestamp | + +## 依赖关系 + +PL/Java依赖JDK环境,目前MogDB中已包含JDK环境,无需用户安装。如果用户已安装(相同或不同版本的)JDK,也不会引起冲突,MogDB会使用Huawei JDK V100R001C00SPC190B003-b09来运行PL/Java。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/MogDB-MySQL-compatibility.md b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/MogDB-MySQL-compatibility.md new file mode 100644 index 00000000..ae4111ac --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/MogDB-MySQL-compatibility.md @@ -0,0 +1,30 @@ +--- +title: MySQL兼容增强 +summary: MySQL兼容增强 +author: Zhang Cuiping +date: 2022-06-21 +--- + +# MySQL兼容增强 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +本特性主要从以下三方面增强MogDB与MySQL的兼容性。同时,支持兼容Insert语法,Insert into可以简写为insert。 + +支持用户锁,允许用户通过sql加自定义的锁,可以让多个程序之间完成加锁相关的交互过程,使得客户端从任何位置访问都可以得到一致性的锁视图。 + +支持建表插入数据时默认记录插入当前时间;更新数据时,如果未指定更新时间,默认显示数据变更的当前时间。 + +支持设置会话级SQL模式,允许运行时变更、全局变更以及会话内变更。 + +## 客户价值 + +通过设置用户锁,对数据、数据结构或者某些字符串进行保护,避免会话之间相互干扰,保证了信息的一致性和安全性。解决了用户业务数据写入与修改时,记录其操作时间戳的问题。通过设置sql模式,可以解决早期版本遗留问题与后期版本的兼容性。 + +## 相关页面 + +[CREATE TABLE](../../reference-guide/sql-syntax/CREATE-TABLE.md), [ALTER TABLE](../../reference-guide/sql-syntax/ALTER-TABLE.md), [INSERT](../../reference-guide/sql-syntax/INSERT.md),[咨询锁函数](../../reference-guide/functions-and-operators/24-system-management-functions/7-advisory-lock-functions.md),[SQL模式](../../reference-guide/guc-parameters/SQL-mode.md),[dolphin插件](../../reference-guide/oracle-plugins/dolphin.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/MogDB-Oracle-compatibility.md b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/MogDB-Oracle-compatibility.md new file mode 100644 index 00000000..07a526ec --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/application-development-interfaces/MogDB-Oracle-compatibility.md @@ -0,0 +1,30 @@ +--- +title: 兼容Oracle +summary: 兼容Oracle +author: Zhang Cuiping +date: 2022-06-17 +--- + +# 兼容Oracle + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +MogDB使用whale插件兼容Oracle的相关函数以及package功能。 + +函数部分,主要新增instrb,nls_charset_id,nls_charset_name,nls_lower,nls_upper, ora_hash, remainder,replace,show,show_parameter,to_timestamp, to_yminterval,tz_offset,nullif,ratio_to_report等。 + +package一般只用于存储过程中,根据ORACLE数据的package规则,新package放到对应的schema下。支持的Oracle管理包有dbms_random,dbms_output,dbms_lock,dbms_application_info,dbms_metadata,dbms_job,dbms_utility。 + +有关函数以及package详情,请参见[whale插件](../../reference-guide/oracle-plugins/whale.md)。 + +## 客户价值 + +通过使用whale插件,增强MogDB与Oracle的兼容性,增强MogDB的功能。 + +## 相关页面 + +[whale插件](../../reference-guide/oracle-plugins/whale.md),[字符处理函数和操作符](../../reference-guide/functions-and-operators/3-character-processing-functions-and-operators.md),[数字操作函数和操作符](../../reference-guide/functions-and-operators/7-mathematical-functions-and-operators.md),[时间和日期处理函数和操作符](../../reference-guide/functions-and-operators/8-date-and-time-processing-functions-and-operators.md),[HLL函数和操作符](../../reference-guide/functions-and-operators/13.1-hll-functions-and-operators.md),[窗口函数](../../reference-guide/functions-and-operators/18-window-functions.md),[系统信息函数](../../reference-guide/functions-and-operators/23-system-information-functions.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/characteristic-description-overview.md b/product/zh/docs-mogdb/v3.1/characteristic-description/characteristic-description-overview.md new file mode 100644 index 00000000..b6ecdbf6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/characteristic-description-overview.md @@ -0,0 +1,112 @@ +--- +title: 特性描述 +summary: 特性描述 +author: Guo Huan +date: 2022-09-01 +--- + +# 特性描述 + +MogDB 3.0版本具有以下特性: + ++ 高性能 + + [CBO优化器](./high-performance/1-cbo-optimizer.md) + + [支持LLVM](./high-performance/2-llvm.md) + + [向量化引擎](./high-performance/3-vectorized-engine.md) + + [行列混合存储](./high-performance/4-hybrid-row-column-store.md) + + [自适应压缩](./high-performance/5-adaptive-compression.md) + + [SQL by pass](./high-performance/6-sql-by-pass.md) + + [鲲鹏NUMA架构优化](./high-performance/7-kunpeng-numa-architecture-optimization.md) + + [支持线程池高并发](./high-performance/8-high-concurrency-of-thread-pools.md) + + [SMP并行执行](./high-performance/9-smp-for-parallel-execution.md) + + [Xlog no Lock Flush](./high-performance/10-xlog-no-lock-flush.md) + + [Parallel Page-based Redo For Ustore](./high-performance/11-parallel-page-based-redo-for-ustore.md) + + [行存转向量化](./high-performance/12-row-store-execution-to-vectorized-execution.md) ++ 高可用 + + [主备机](./high-availability/1-primary-standby.md) + + [逻辑复制](./high-availability/2-logical-replication.md) + + [在线节点替换](./high-availability/3-online-node-replacement.md) + + [逻辑备份](./high-availability/4-logical-backup.md) + + [物理备份](./high-availability/5-physical-backup.md) + + [作业失败自动重试](./high-availability/6-automatic-job-retry-upon-failure.md) + + [极致RTO](./high-availability/7-ultimate-rto.md) + + [级联备机](./high-availability/8-cascaded-standby-server.md) + + [延时回放](./high-availability/9-delayed-replay.md) + + [备机增加删除](./high-availability/10-adding-or-deleting-a-standby-server.md) + + [延迟进入最大可用模式](./high-availability/11-delaying-entering-the-maximum-availability-mode.md) + + [并行逻辑解码](./high-availability/12-parallel-logical-decoding.md) + + [DCF](./high-availability/13-dcf.md) + + [CM](./high-availability/14-cm.md) + + [支持global syscache](./high-availability/15-global-syscache.md) + + [支持备机build备机](./high-availability/16-using-a-standby-node-to-build-a-standby-node.md) ++ 维护性 + + [灰度升级](./maintainability/1-gray-upgrade.md) + + [支持WDR诊断报告](./maintainability/2-workload-diagnosis-report.md) + + [慢SQL诊断](./maintainability/3-slow-sql-diagnosis.md) + + [Session性能诊断](./maintainability/4-session-performance-diagnosis.md) + + [系统KPI辅助诊断](./maintainability/5-system-kpi-aided-diagnosis.md) + + [故障诊断](./maintainability/fault-diagnosis.md) ++ 数据库安全 + + [访问控制模型](./database-security/1-access-control-model.md) + + [控制权和访问权分离](./database-security/2-separation-of-control-and-access-permissions.md) + + [数据库认证机制](./database-security/3-database-encryption-authentication.md) + + [数据加密存储](./database-security/4-data-encryption-and-storage.md) + + [数据库审计](./database-security/5-database-audit.md) + + [网络通信安全](./database-security/6-network-communication-security.md) + + [资源标签机制](./database-security/7-resource-label.md) + + [统一审计机制](./database-security/8-unified-audit.md) + + [动态数据脱敏机制](./database-security/9-dynamic-data-anonymization.md) + + [行级访问控制](./database-security/10-row-level-access-control.md) + + [用户口令强度校验机制](./database-security/11-password-strength-verification.md) + + [全密态数据库等值查询](./database-security/12-equality-query-in-a-fully-encrypted-database.md) + + [账本数据库机制](./database-security/13-ledger-database-mechanism.md) + + [透明数据加密](./database-security/14-transparent-data-encryption.md) ++ 企业级特性 + + [函数及存储过程支持](./enterprise-level-features/1-support-for-functions-and-stored-procedures.md) + + [支持SQL hint](./enterprise-level-features/2-sql-hints.md) + + [全文索引](./enterprise-level-features/3-full-text-indexing.md) + + [Copy接口支持容错机制](./enterprise-level-features/4-copy-interface-for-error-tolerance.md) + + [分区](./enterprise-level-features/5-partitioning.md) + + [高级分析函数支持](./enterprise-level-features/6-support-for-advanced-analysis-functions.md) + + [物化视图](./enterprise-level-features/7-materialized-view.md) + + [支持HyperLogLog](./enterprise-level-features/8-hyperloglog.md) + + [在线添加索引](./enterprise-level-features/9-creating-an-index-online.md) + + [自治事务](./enterprise-level-features/10-autonomous-transaction.md) + + [全局临时表](./enterprise-level-features/11-global-temporary-table.md) + + [伪列ROWNUM](./enterprise-level-features/12-pseudocolumn-rownum.md) + + [支持存储过程调试](./enterprise-level-features/13-stored-procedure-debugging.md) + + [JDBC客户端负载均衡与读写分离](./enterprise-level-features/14-jdbc-client-load-balancing-and-readwrite-isolation.md) + + [In-place Update存储引擎](./enterprise-level-features/15-in-place-update-storage-engine.md) + + [发布订阅](./enterprise-level-features/16-publication-subscription.md) + + [外键锁增强](./enterprise-level-features/17-foreign-key-lock-enhancement.md) + + [支持OLTP场景数据压缩](./enterprise-level-features/18-data-compression-in-oltp-scenarios.md) + + [事务异步提交](./enterprise-level-features/19-transaction-async-submit.md) + + [索引创建并行控制](./enterprise-level-features/23-index-creation-parallel-control.md) + + [动态分区裁剪](./enterprise-level-features/21-dynamic-partition-pruning.md) + + [COPY导入优化](./enterprise-level-features/20-copy-import-optimization.md) + + [SQL运行时状态观测](./enterprise-level-features/22-sql-running-status-observation.md) + + [BRIN索引](./enterprise-level-features/24-brin-index.md) + + [BLOOM索引](./enterprise-level-features/25-bloom-index.md) ++ 应用开发接口 + + [支持标准SQL](./application-development-interfaces/1-standard-sql.md) + + [支持标准开发接口](./application-development-interfaces/2-standard-development-interfaces.md) + + [PG接口兼容](./application-development-interfaces/3-postgresql-api-compatibility.md) + + [支持PL/Java](./application-development-interfaces/4-pl-java.md) + + [Oracle兼容增强](./application-development-interfaces/MogDB-Oracle-compatibility.md) + + [MySQL兼容增强](./application-development-interfaces/MogDB-MySQL-compatibility.md) ++ AI能力 + + AI4DB:数据库自治运维 + + [数据库指标采集、预测与异常监控](./ai-capabilities/ai4db-autonomous-database-o-m/1-database-metric-collection-forecast-and-exception-detection.md) + + [慢SQL根因分析](./ai-capabilities/ai4db-autonomous-database-o-m/2-root-cause-analysis-for-slow-sql-statements.md) + + [索引推荐](./ai-capabilities/ai4db-autonomous-database-o-m/3-index-recommendation.md) + + [参数调优与诊断](./ai-capabilities/ai4db-autonomous-database-o-m/4-parameter-tuning-and-diagnosis.md) + + [慢SQL发现](./ai-capabilities/ai4db-autonomous-database-o-m/5-slow-sql-statement-discovery.md) + + [DB4AI:数据库驱动AI](./ai-capabilities/db4ai-database-driven-ai.md) + + AI in DB:数据库内AI功能 + + [Predictor:AI查询时间预测](./ai-capabilities/ai-in-db/predictor-ai-query-time-forecasting.md) ++ 工具链 + + [MySQL->MogDB迁移工具chameleon](./tool-chain/mysql-to-mogdb-migration-tool-chameleon.md) + + [MogDB客户端工具DataStudio](./tool-chain/mogdb-client-tool-datastudio.md) ++ 中间件 + + [分布式数据库能力](./middleware/distributed-database-capability.md) + + [使用kubernetes部署分布式数据库](./middleware/deploying-a-distributed-database-using-kubernetes.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/1-access-control-model.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/1-access-control-model.md new file mode 100644 index 00000000..517d6b76 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/1-access-control-model.md @@ -0,0 +1,41 @@ +--- +title: 访问控制模型 +summary: 访问控制模型 +author: Guo Huan +date: 2022-05-07 +--- + +# 访问控制模型 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +管理用户访问权限,为用户分配完成任务所需要的最小权限。 + +## 客户价值 + +客户依据自身需求创建对应的数据库用户并赋予相应的权限给操作人员,将数据库使用风险降到最低。 + +## 特性描述 + +数据库提供了基于角色的访问控制模型和基于三权分立的访问控制模型。在基于角色的访问控制模型下,数据库用户可分为系统管理员用户、监控管理员用户、运维管理员用户、安全策略管理员用户以及普通用户。系统管理员创建角色或者用户组,并为角色分配对应的权限;监控管理员查看dbe_perf模式下的监控视图或函数;运维管理员使用Roach工具执行数据库备份恢复操作;安全策略管理员创建资源标签、脱敏策略、统一审计策略。用户通过绑定不同的角色获得角色所拥有的对应的操作权限。 + +在基于三权分立的访问控制模型下,数据库用户可分为系统管理员、安全管理员、审计管理员、监控管理员用户、运维管理员用户、安全策略管理员用户以及普通用户。安全管理员负责创建用户,系统管理员负责为用户赋权,审计管理员负责审计所有用户的行为。 + +默认情况下,使用基于角色的访问控制模型。客户可通过设置GUC参数enableSeparationOfDuty为on来切换。 + +## 特性增强 + +无。 + +## 特性约束 + +- 系统管理员的具体权限受GUC参数enableSeparationOfDuty控制。 +- 三权分立开关和关闭切换时需要重启数据库,且无法对新模型下不合理的用户权限进行自主识别,需要DBA识别并修正。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/10-row-level-access-control.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/10-row-level-access-control.md new file mode 100644 index 00000000..6d47500a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/10-row-level-access-control.md @@ -0,0 +1,43 @@ +--- +title: 行级访问控制 +summary: 行级访问控制 +author: Guo Huan +date: 2022-05-07 +--- + +# 行级访问控制 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +行级访问控制特性将数据库访问控制精确到数据表行级别,使数据库达到行级访问控制的能力。不同用户执行相同的SQL查询操作,读取到的结果是不同的。 + +## 客户价值 + +不同用户执行相同的SQL查询操作,读取到的结果是不同的。 + +## 特性描述 + +用户可以在数据表创建行访问控制(Row Level Security)策略,该策略是指针对特定数据库用户、特定SQL操作生效的表达式。当数据库用户对数据表访问时,若SQL满足数据表特定的Row Level Security策略,在查询优化阶段将满足条件的表达式,按照属性(PERMISSIVE | RESTRICTIVE)类型,通过AND或OR方式拼接,应用到执行计划上。 + +行级访问控制的目的是控制表中行级数据可见性,通过在数据表上预定义Filter,在查询优化阶段将满足条件的表达式应用到执行计划上,影响最终的执行结果。当前受影响的SQL语句包括SELECT,UPDATE,DELETE。 + +## 特性增强 + +无。 + +## 特性约束 + +- 行级访问控制策略仅可以应用到SELECT、UPDATE和DELETE操作,不支持应用到INSERT和MERGE操作。 +- 支持对行存表、行存分区表、列存表、列存分区表、复制表、unlogged表、hash表定义行级访问控制策略,不支持HDFS表、外表、临时表定义行级访问控制策略。 +- 不支持对视图定义行级访问控制策略。 +- 同一张表上可以创建多个行级访问控制策略,一张表最多允许创建100个行级访问控制策略。 +- 初始用户和系统管理员不受行级访问控制策略的影响。 +- 对于设置了行级访问控制策略的表,需要谨慎授予其他用户对该表的trigger权限,以免其他用户利用触发器绕过行级访问控制策略。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/11-password-strength-verification.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/11-password-strength-verification.md new file mode 100644 index 00000000..7bc45d05 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/11-password-strength-verification.md @@ -0,0 +1,71 @@ +--- +title: 用户口令强度校验机制 +summary: 用户口令强度校验机制 +author: Guo Huan +date: 2022-05-07 +--- + +# 用户口令强度校验机制 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +对用户访问数据库所设置的口令强度进行校验。 + +## 客户价值 + +用户无法设置过低强度的口令,加固客户数据安全。 + +## 特性描述 + +初始化数据库、创建用户、修改用户时需要指定密码。密码必须满足强度校验,否则会提示用户重新输入密码。账户密码复杂度要求如下: + +- 包含大写字母(A-Z)的最少个数(password_min_uppercase) +- 包含小写字母(a-z)的最少个数(password_min_lowercase) +- 包含数字(0-9)的最少个数(password_min_digital) +- 包含特殊字符的最少个数(password_min_special) +- 密码的最小长度(password_min_length) +- 密码的最大长度(password_max_length) +- 至少包含上述四类字符中的三类。 +- 不能和用户名、用户名倒写相同,本要求为非大小写敏感。 +- 不能和当前密码、当前密码的倒写相同。 +- 不能是弱口令。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 弱口令指的是强度较低,容易被破解的密码,对于不同的用户或群体,弱口令的定义可能会有所区别,用户需要自己添加定制化的弱口令。 + +参数password_policy设置为1时表示采用密码复杂度校验,默认值为1。 + +弱口令字典中的口令存放在gs_global_config系统表中(name字段为weak_password的记录是储存的弱口令),当创建用户、修改用户需要设置密码时,将会把用户设置口令和弱口令字典中存放的口令进行对比,如果命中,则会提示用户该口令为弱口令,设置密码失败。 + +弱口令字典默认为空,用户通过以下语法可以对弱口令字典进行增加和删除,示例如下: + +```sql +CREATE WEAK PASSWORD DICTIONARY WITH VALUES ('password1'), ('password2'); +DROP WEAK PASSWORD DICTIONARY; +``` + +其中“password1”,“password2”是用户事先准备的弱口令,该语句执行成功后将会存入弱口令系统表中。 + +当用户尝试通过CREATE WEAK PASSWORD DICTIONARY 插入表中已存在的弱口令时,会只在表中保留一条该弱口令。 + +DROP WEAK PASSWORD DICTIONARY语句会清空整张系统表弱口令相关部分。 + +gs_global_config系统表没有唯一索引,不建议用户通过COPY FROM命令重复用相同数据对该表进行操作。 + +若用户需要对弱口令相关操作进行审计,应设置audit_system_object参数中的第三位为1。 + +## 特性增强 + +MogDB 1.1.0版本实现了弱口令字典功能。 + +## 特性约束 + +- 初始用户、系统管理员和安全管理员可以查看、新增、删除弱口令字典。 +- 普通用户可以查看但是不能新增或者删除弱口令字典。 + +## 依赖关系 + +无。 diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/12-equality-query-in-a-fully-encrypted-database.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/12-equality-query-in-a-fully-encrypted-database.md new file mode 100644 index 00000000..e70a8115 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/12-equality-query-in-a-fully-encrypted-database.md @@ -0,0 +1,110 @@ +--- +title: 全密态数据库等值查询 +summary: 全密态数据库等值查询 +author: Guo Huan +date: 2022-05-07 +--- + +# 全密态数据库等值查询 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +密态数据库意在解决数据全生命周期的隐私保护问题,使得系统无论在何种业务场景和环境下,数据在传输、运算以及存储的各个环节始终都处于密文状态。当数据拥有者在客户端完成数据加密并发送给服务端后,在攻击者借助系统脆弱点窃取用户数据的状态下仍然无法获得有效的价值信息,从而起到保护数据隐私的作用。 + +## 客户价值 + +由于整个业务数据流在数据处理过程中都是以密文形态存在,通过全密态数据库,可以实现: + +1. 保护数据在云上全生命周期的隐私安全,无论数据处于何种状态,攻击者都无法从数据库服务端获取有效信息。 +2. 帮助云服务提供商获取第三方信任,无论是企业服务场景下的业务管理员、运维管理员,还是消费者云业务下的应用开发者,用户通过将密钥掌握在自己手上,使得高权限用户无法获取数据有效信息。 +3. 让云数据库借助全密态能力更好的遵守个人隐私保护方面的法律法规。 + +## 特性描述 + +从用户视角来看,整个密态等值查询的主要功能分为三部分,主要通过新增的KeyTool工具以及MogDB的增强gsql客户端来实现。 + +首先是客户端密钥管理功能,用户借助新增的KeyTool工具来实现CMK的生成、销毁和更新,同时支持密钥导入导出。通过该KeyTool工具的导入导出功能,CMK可以在不同的客户端间进行传输;同时,KeyTool实现了单个客户端侧的密钥管理,通过配置管理文件,可以对密钥的存储、更新进行管理。 + +其次该特性提供密钥创建功能和加密表创建功能,通过新增SQL语法“CREATE CLINET MASTER KEY”和“CREATE COLUMN ENCRYPTION KEY”实现在数据库侧记录和管理CMK和CEK元信息,CMK和CEK信息被记录在新增的系统表中。通过扩展“CREATE TABLE”语法为表的每一个敏感信息列指定列加密密钥和加密算法,方便后续数据密文存储。 + +最后该特性对用户提供密态等值查询能力,该部分功能是整个特性的核心,虽然用户对整个密文查询无感知,但是在指定数据的加密信息后,针对该敏感数据的查询将受限于当前密态等值查询的支持规格。 + +从整体视角来看,该特性所实现的功能主要是为了用户基于敏感数据保护的诉求来存储管理数据并基于密文数据信息实现查询任务。 + +## 特性增强 + +无。 + +## 特性约束 + +- 数据以列级别进行加密,而无法按照行级别区分加密策略。 + +- 除Rename操作外,不支持通过Alter Table语法实现对加密表列的更改(包括加密列和非加密列之间的互转换),支持添加(Add)和删除(Drop)对应的加密列。 + +- 不支持对加密列设置大部分check限制性语法,但是支持check(column is not null)语法。 + +- 当support_extended_features = off时,不支持对加密列使用primary key、unique。当support_extended_features = on时,仅支持确定性加密列使用primary key、unique。 + +- 不支持不同数据类型之间的隐式转换。 + +- 不支持不同数据类型密文间的集合操作。 + +- 不支持加密列创建范围分区。 + +- 加密列仅支持repeat和empty_blob()函数。 + +- 当前版本只支持gsql和JDBC(部署在linux操作系统)客户端,暂不支持ODBC等其他客户端实现密态等值查询。 + +- 使用JDBC客户端时,密态等值查询特性不能与负载均衡或自动选主特性同时开启。 + +- 只支持通过客户端执行copy from stdin的方式、\copy命令的方式以及insert into values(…)的方式往密态表中导入数据。 + +- 不支持从加密表到文件之间的copy操作。 + +- 不支持包括排序、范围查询以及模糊查询等在内的除等值以外的各种密态查询。 + +- 支持部分函数存储过程密态语法,密态支持函数存储过程具体约束查看开发者指南密态支持函数/存储过程章节。 + +- 不支持通过insert into…select…,merge into语法将非加密表数据插入到加密表数据中。 + +- 对于处于连接状态的连接请求,只有触发更新缓存的操作(更改用户,解密加密列失败等)和重新建连后才能感知服务端CEK信息变更。 + +- 不支持在由随机加密算法加密的列上进行密态等值查询。 + +- 对于密态等值查询运算中如果参与比较的两个属性条件采用不同的数据加密密钥,返回报错。 + +- 密态等值查询不支持时序表、外表,不支持ustore存储引擎加密。 + +- 对于数据库服务侧配置变更(pg_settings系统表、权限、密钥和加密列等信息), 需要重新建立JDBC连接保证配置变更生效。 + +- 不支持多条SQL语句一起执行,insert into语句多批次执行场景不受此条约束限制。 + +- 密态等值查询支持的数据类型包括: + + | 数据类 | 类型 | 描述 | + | ---------- | ------------------ | ----------------------------------- | + | 整型 | tinyint/tinyint(n) | 微整数,同int1 | + | | smallint | 小整数,同int2 | + | | int4 | 常用整数 | + | | binary_integer | Oracle兼容类型,常用整数 | + | | bigint/bigint(n) | 大整数,同int8 | + | 数值类型 | numeric(p,s) | 精度为p的准确数值类型 | + | | number | Oracle兼容类型,等同numeric(p,s) | + | 浮点类型 | float4 | 单精度浮点数 | + | | float8 | 双精度浮点数 | + | | double precision | 双精度浮点数 | + | 字符类型 | char/char(n) | 定长字符串,不足补空格,默认精度为1 | + | | varchar(n) | 变长字符串,n是指允许的最大字节长度 | + | | text | 文本类型 | + | | varchar2(n) | Oracle兼容类型,等同varchar(n) | + | | clob | 大文本类型 | + | 二进制类型 | bytea | 变长的二进制字符串 | + | | blob | 二进制大对象 | + +## 依赖关系 + +无。 diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/13-ledger-database-mechanism.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/13-ledger-database-mechanism.md new file mode 100644 index 00000000..8888f0bc --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/13-ledger-database-mechanism.md @@ -0,0 +1,43 @@ +--- +title: 账本数据库机制 +summary: 账本数据库机制 +author: Guo Huan +date: 2022-05-07 +--- + +# 账本数据库机制 + +## 可获得性 + +本特性自MogDB 2.1.0版本开始引入。 + +## 特性简介 + +账本数据库特性,对用户指定的防篡改表增加校验信息,并记录用户对其数据的操作历史,通过数据和操作历史的一致性校验来保证用户数据无法被恶意篡改。在用户对防篡改表执行DML操作时,系统对防篡改表增加少量额外的行级校验信息,同时记录操作的SQL语句和数据的变化历史。通过特性提供的校验接口,用户可以方便的校验防篡改表中的数据与系统记录的操作信息是否一致。 + +## 客户价值 + +账本数据库通过提供对用户数据的操作记录、数据历史变化记录以及易用的一致性的校验接口,方便用户随时校验数据库中的敏感信息是否发生恶意篡改,有效提高数据库防篡改能力。 + +## 特性描述 + +账本数据库采用账本Schema对普通表和防篡改用户表进行隔离。用户在账本Schema中创建的行存表具有防篡改属性,即为防篡改用户表。用户向防篡改用户表中插入数据时,系统会自动生成少量行级校验信息。在用户执行DML时,系统会在全局区块表(GS_GLOBAL_CHAIN)中记录用户的操作、在用户表相应的历史表中记录数据的更改等信息,操作记录、数据变化记录和用户表中的数据三者严格保持一致。账本数据库提供高性能校验接口,能够供用户方便的校验数据的一致性,如果一致性校验失败,则说明数据可能发生篡改,需要及时联系审计管理员回溯操作记录历史。 + +## 特性增强 + +无。 + +## 特性约束 + +- 防篡改模式下的行存表具有防篡改属性,而临时表、UNLOGGED表、列存表、时序表等均不具有防篡改属性。 +- 不允许修改防篡改用户表的结构,不允许truncate防篡改相关表,不允许将防篡改用户表切换到普通的Schema中,不允许将非防篡改表切换到防篡改Schema中。 +- 防篡改表如果为分区表,则不支持exchange partition、drop partition、truncate partition等操作。 +- 不支持使用函数、TRIGGER修改防篡改用户表数据。 +- 防篡改用户表创建时不能有名为“hash”的列。 +- 普通用户调用篡改校验接口只能校验自己有权查询的表。 +- 只允许审计管理员和初始用户查询全局区块表和BLOCKCHAIN模式中的表,普通用户无权访问,所有用户均无权修改。 +- 根据用户历史表命名规则,若待创建表的Schema或表名以'_'结尾或开头,可能会出现对应历史表名与已有表名冲突的情况,需要重新命名。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/14-transparent-data-encryption.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/14-transparent-data-encryption.md new file mode 100644 index 00000000..b535431e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/14-transparent-data-encryption.md @@ -0,0 +1,53 @@ +--- +title: 透明数据加密 +summary: 透明数据加密 +author: Guo Huan +date: 2022-05-07 +--- + +# 透明数据加密 + +## 可获得性 + +本特性自MogDB 2.1.0版本开始引入。 + +## 特性简介 + +透明数据加密(Transparent Data Encryption),是数据库在将数据写入存储介质时对数据进行加密,从存储介质中读取数据时自动解密,防止攻击者绕过数据库认证机制直接读取数据文件中的数据,以解决静态数据泄露问题。该功能对于应用层几乎透明无感知,用户可根据需要决定是否启用透明数据加密功能。 + +## 客户价值 + +为了防止攻击者绕过数据库认证机制直接读取数据文件中的数据,可以通过透明数据加密功能对数据库的数据文件进行加密,保证用户必须在数据库启动后通过正常途径连接数据库,才可以读取解密后的数据,达到数据保护的目的。 + +## 特性描述 + +采用三层密钥结构实现密钥管理机制,即根密钥(RK)、主密钥(CMK)和数据加密密钥(DEK)。主密钥由根密钥加密保护,数据加密密钥由主密钥加密保护。数据加密密钥用于对用户数据进行加密和解密,每个表对应一个数据加密密钥。 + +支持表级加密,允许用户在创建表时指定是否对表进行加密和使用的加密算法,加密算法支持AES_128_CTR和SM4_CTR两种算法,算法一旦指定不可更改。对于创建表时指定为加密的表,数据库会自动为该表申请创建数据加密密钥,并将加密算法、密钥密文和对应主密钥ID等参数使用”keyword=value”格式保存在pg_class系统表中的reloptions字段中。 + +对于加密表,允许用户切换表的加密状态,即将加密表切换为非加密表,或将非加密表切换为加密表。如果在创建表时未使能加密功能,后续无法再切换为加密表。 + +对于加密表,支持数据加密密钥轮转。密钥轮转后,使用旧密钥加密的数据仍使用旧密钥解密,新写入的数据使用新密钥加密。密钥轮转时不更换加密算法。 + +## 特性增强 + +无。 + +## 特性约束 + +当前版本主要实现对接KMS服务,支持表级密钥存储,实现对行存表加密,规格约束如下: + +- 支持heap存储行存表加密。 +- 不支持列存加密,不支持物化视图加密,不支持ustore存储引擎加密。 +- 不支持索引和Sequence加密,不支持XLOG日志加密,不支持MOT内存表加密,不支持系统表加密。 +- 用户在创建表时可以指定加密算法,加密算法一旦指定不可更改。如果创建表时设置enable_tde为on,但是不指定加密算法encrypt_algo,则默认使用AES_128_CTR加密算法。 +- 如果在创建表时未开启加密功能或指定加密算法,后续无法再切换为加密表。 +- 对于已分配加密密钥的表,切换表的加密和非加密状态,不会更换密钥和加密算法。 +- 数据密钥轮转只有开启表加密功能时才支持轮转。 +- 不支持单集群跨region的多副本主备同步,不支持单集群跨region的扩容,不支持跨region的备份恢复、集群容灾和数据迁移场景。 +- 混合云场景如果使用KMS和管控面功能,则可以支持透明数据加密,其他KMS服务如果接口不兼容则无法支持。 +- 加密表的查询性能比不加密时会有所劣化,对于性能有较高要求的情况下需谨慎开启加密功能。 + +## 依赖关系 + +依赖KMS提供密钥管理服务。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/2-separation-of-control-and-access-permissions.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/2-separation-of-control-and-access-permissions.md new file mode 100644 index 00000000..9405164f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/2-separation-of-control-and-access-permissions.md @@ -0,0 +1,46 @@ +--- +title: 控制权和访问权分离 +summary: 控制权和访问权分离 +author: Guo Huan +date: 2022-05-07 +--- + +# 控制权和访问权分离 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +支持控制权和访问权分离。 + +## 客户价值 + +针对管理员用户,表对象的控制权和访问权要能够分离,提高普通用户数据安全性。 + +## 特性描述 + +对于有多个业务部门,各部门间使用不同的数据库用户进行业务操作,同时有一个同级的数据库维护部门使用数据库管理员进行维护操作的场景下,业务部门可能希望在未经授权的情况下,管理员用户只能对各部门的数据进行控制操作(DROP、ALTER、TRUNCATE),但是不能进行访问操作(INSERT、DELETE、UPDATE、SELECT、COPY)。即针对管理员用户,表对象的控制权和访问权要能够分离,提高普通用户数据安全性。 + +三权分立情况下,管理员对其他用户放在属于各自模式下的表无权限。但是,这种无权限包含了无控制权限,因此不能满足上面的诉求。为此,MogDB提供了私有用户方案。即在非三权分立模式下,创建具有INDEPENDENT属性的私有用户。具备CREATEROLE权限或者是系统管理员权限的用户可以创建私有用户或者修改普通用户的属性为私有用户,普通用户也可以修改自己的属性为私有用户。 + +``` +MogDB=# CREATE USER user_independent WITH INDEPENDENT IDENTIFIED BY "1234@abc"; +``` + +针对该用户的表对象,系统管理员在未经其授权前,只能进行控制操作(DROP、ALTER、TRUNCATE),无权进行INSERT、DELETE、SELECT、UPDATE、COPY、GRANT、REVOKE、ALTER OWNER操作。 + +## 特性增强 + +无。 + +## 特性约束 + +对于私有用户的表,需要谨慎授予其他用户对该表的trigger权限,以免其他用户利用触发器查看私有用户的数据。 + +若将私有用户表的相关权限授予其他非私有用户,系统管理员也会获得同样的权限。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/3-database-encryption-authentication.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/3-database-encryption-authentication.md new file mode 100644 index 00000000..c8596459 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/3-database-encryption-authentication.md @@ -0,0 +1,36 @@ +--- +title: 数据库认证机制 +summary: 数据库认证机制 +author: Guo Huan +date: 2022-05-07 +--- + +# 数据库认证机制 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +提供基于客户端/服务端(C/S)模式的客户端连接认证机制。 + +## 客户价值 + +加密认证过程中采用单向Hash不可逆加密算法PBKDF2,有效防止彩虹攻击。 + +## 特性描述 + +MogDB采用基本的客户端连接认证机制,客户端发起连接请求后,由服务端完成信息校验并依据校验结果发送认证所需信息给客户端(认证信息包括盐值,token以及服务端签名信息)。客户端响应请求发送认证信息给服务端,由服务端调用认证模块完成对客户端认证信息的认证。用户的密码被加密存储在内存中。整个过程中口令加密存储和传输。当用户下次登录时通过计算相应的hash值并与服务端存储的key值比较来进行正确性校验。 + +## 特性增强 + +统一加密认证过程中的消息处理流程,可有效防止攻击者通过抓取报文猜解用户名或者密码的正确性。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/4-data-encryption-and-storage.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/4-data-encryption-and-storage.md new file mode 100644 index 00000000..9292acf2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/4-data-encryption-and-storage.md @@ -0,0 +1,44 @@ +--- +title: 数据加密存储 +summary: 数据加密存储 +author: Guo Huan +date: 2022-05-07 +--- + +# 数据加密存储 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +提供对导入数据的加密存储。 + +## 客户价值 + +为客户提供加密导入接口,对客户认为是敏感信息的数据进行加密后存储在表内。 + +## 特性描述 + +MogDB提供加密函数gs_encrypt_aes128()、gs_encrypt()和解密函数gs_decrypt_aes128()、gs_decrypt()接口。通过加密函数,可以对需要输入到表内的某列数据进行加密后再存储到表格内。调用格式为: + +**gs_encrypt_aes128(column, key),gs_encrypt(decryptstr,keystr,decrypttype)** + +其中key为用户指定的初始口令,用于派生加密密钥。当客户需要对整张表进行加密处理时,则需要为每一列单独书写加密函数。 + +当具有对应权限的用户需要查看具体的数据时,可通过解密函数接口对相应的属性列进行解密处理,调用格式为: + +**gs_decrypt_aes128(column, key),gs_decrypt(decryptstr,keystr,decrypttype)** + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/5-database-audit.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/5-database-audit.md new file mode 100644 index 00000000..8721b874 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/5-database-audit.md @@ -0,0 +1,36 @@ +--- +title: 数据库审计 +summary: 数据库审计 +author: Guo Huan +date: 2022-05-07 +--- + +# 数据库审计 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +审计日志记录用户对数据库的启停、连接、DDL、DML、DCL等操作。 + +## 客户价值 + +审计日志机制主要增强数据库系统对非法操作的追溯及举证能力。 + +## 特性描述 + +数据库安全对数据库系统来说至关重要。MogDB将用户对数据库的所有操作写入审计日志。数据库安全管理员可以利用这些日志信息,重现导致数据库现状的一系列事件,找出非法操作的用户、时间和内容等。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/6-network-communication-security.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/6-network-communication-security.md new file mode 100644 index 00000000..bcd549f6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/6-network-communication-security.md @@ -0,0 +1,44 @@ +--- +title: 网络通信安全 +summary: 网络通信安全 +author: Guo Huan +date: 2022-05-07 +--- + +# 网络通信安全 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +为保护敏感数据在Internet上传输的安全性,MogDB支持通过SSL加密客户端和服务器之间的通讯。 + +## 客户价值 + +保证客户的客户端与服务器通讯安全。 + +## 特性描述 + +MogDB支持SSL协议标准。SSL(Secure Socket Layer)协议是一种安全性更高的应用层通信协议,主要用于Web安全传输,SSL包含记录层和传输层,记录层协议确定传输层数据的封装格式,传输层安全协议使用X.509认证。SSL协议利用非对称加密演算来对通信方做身份认证,之后交换对称密钥作为会谈密钥。通过SSL协议可以有效保障两个应用间通信的保密性和可靠性,使客户与服务器之间的通信不被攻击者窃听。 + +MogDB支持TLS 1.2协议标准。TLS 1.2协议是一种安全性更高的传输层通信协议,它包括两个协议组,TLS记录协议和TLS握手协议,每一组协议具有很多不同格式的信息。TLS协议是独立于应用协议的,高层协议可以透明地分布在TLS协议上面。通过TLS协议可保证通信双方的数据保密性和数据完整性。 + +## 特性增强 + +证书签名算法强度检查:对于一些强度较低的签名算法,给出告警信息,提醒客户更换包含高强度签名算法的证书。 + +证书超时时间检查:如果距离超期日期小于7天则给出告警信息,提醒客户端更换证书。 + +证书权限检查:在创建连接阶段对证书的权限进行校验。 + +## 特性约束 + +从CA认证中心申请到正式的服务器、客户端的证书和密钥。(假设服务器的私钥为server.key,证书为server.crt,客户端的私钥为client.key,证书为client.crt,CA根证书名称为cacert.pem。) + +需要打开SSL开关,并且配置证书和连接方式。 + +## 依赖关系 + +OpenSSL \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/7-resource-label.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/7-resource-label.md new file mode 100644 index 00000000..7fcc2612 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/7-resource-label.md @@ -0,0 +1,49 @@ +--- +title: 资源标签机制 +summary: 资源标签机制 +author: Guo Huan +date: 2022-05-07 +--- + +# 资源标签机制 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +数据库资源是指数据库所记录的各类对象,包括数据库、模式、表、列、视图、触发器等,数据库对象越多,数据库资源的分类管理就越繁琐。资源标签机制是一种通过对具有某类相同“特征”的数据库资源进行分类标记而实现资源分类管理的一种技术。当管理员对数据库内某些资源“打上”标签后,可以基于该标签进行如审计或数据脱敏的管理操作,从而实现对标签所包含的所有数据库资源进行安全管理。 + +## 客户价值 + +合理的制定资源标签能够有效的进行数据对象分类,提高对象管理效率,降低安全策略配置的复杂性。当管理员需要对某组数据库资源对象做统一审计或数据脱敏等安全管理动作时,可将这些资源划分到一个资源标签,该标签即包含了具有某类特征或需要统一配置某种策略的数据库资源,管理员可直接对资源标签执行管理操作,大大降低了策略配置的复杂性和信息冗余程度,提高了管理效率。 + +## 特性描述 + +资源标签机制是将当前数据库内包含的各种资源进行“有选择性的”分类,管理员可以使用如下SQL语法进行资源标签的创建,从而将一组数据库资源打上标签: + +```sql +CREATE RESOURCE LABEL schm_lb ADD SCHEMA (schema_for_label); +CREATE RESOURCE LABEL tb_lb ADD TABLE (schema_for_label.table_for_label); +CREATE RESOURCE LABEL col_lb ADD COLUMN (schema_for_label.table_for_label.column_for_label); +CREATE RESOURCE LABEL multi_lb ADD SCHEMA (schema_for_label), TABLE (table_for_label); +``` + +其中,schema_for_label、table_for_label、column_for_label分别为待标记模式、表、列。schm_lb标签包含了模式schm_for_label;tb_lb包含了表table_for_label;col_lb包含了列column_for_label;multi_lb包含模式schm_for_label和列table_for_label。对这些已配置的资源标签进行如统一审计或动态数据脱敏也即是对标签所包含的每一个数据库资源进行管理。 + +当前,资源标签所支持的数据库资源类型包括:SCHEMA、TABLE、COLUMN、VIEW、FUNCTION。 + +## 特性增强 + +无。 + +## 特性约束 + +- 资源标签需要由具备POLADMIN和SYSADMIN属性的用户或初始用户创建。 +- 不支持对临时表创建资源标签。 +- 同一个基本表的列只可能属于一个资源标签。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/8-unified-audit.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/8-unified-audit.md new file mode 100644 index 00000000..63f970eb --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/8-unified-audit.md @@ -0,0 +1,68 @@ +--- +title: 统一审计机制 +summary: 统一审计机制 +author: Guo Huan +date: 2022-05-07 +--- + +# 统一审计机制 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +审计机制是行之有效的安全管理方案,可有效解决攻击者抵赖,审计的范围越大,可监控的行为就越多,而产生的审计日志就越多,影响实际审计效率。统一审计机制是一种通过定制化审计策略实现高效安全审计管理的技术。当管理员定义审计对象和审计行为后,用户执行的任务如果关联到对应的审计策略,则生成对应的审计行为,并记录审计日志。定制化审计策略可涵盖常见的用户管理活动、DDL和DML行为,满足日常审计诉求。 + +## 客户价值 + +审计是日常安全管理中必不可少的行为,当使用传统审计机制审计某种行为时,如SELECT,会导致产生大量的审计日志,进而增加整个系统的I/O,影响系统的性能;另一方面,大量的审计日志会影响管理员的审计效率。统一审计机制使得客户可以定制化生成审计日志的策略,如只审计数据库账户A查询某个表的行为。通过定制化审计,可以大大减少生成审计日志的数量,从而在保障审计行为的同时降低对系统性能的影响。而定制化审计策略可以提升管理员的审计效率。 + +## 特性描述 + +统一审计机制基于资源标签进行审计行为定制化,且将当前所支持的审计行为划分为access类和privileges类。一个完整的审计策略创建的SQL语法如下所示: + +```sql +CREATE RESOURCE LABEL auditlabel add table(table_for_audit1, table_for_audit2); + +CREATE AUDIT POLICY audit_select_policy ACCESS SELECT ON LABEL(auditlabel) FILTER ON ROLES(usera); + +CREATE AUDIT POLICY audit_admin_policy PRIVILEGES ALTER, DROP ON LABEL(auditlabel) FILTER ON IP(local); +``` + +其中,auditlabel为本轮计划审计的资源标签,该资源标签中包含了两个表对象;audit_select_policy定义了用户usera对auditlabel对象的SELECT行为的审计策略,不区分访问源;audit_admin_policy定义了从本地对auditlabel对象进行ALTER和DROP操作行为的审计策略,不区分执行用户;当不指定ACCESS和PRIVILEGES的具体行为时,表示审计针对某一资源标签的所有支持的DDL和DML行为。当不指定具体的审计对象时,表示审计针对所有对象的操作行为。统一审计策略的增删改也会记录在统一审计日志中。 + +当前,统一审计支持的审计行为包括: + +| SQL类型 | 支持操作和对象类型 | +| ------- | ------------------------------------------------------------ | +| **DDL** | 操作:ALL ALTER ANALYZE COMMENT CREATE DROP GRANT REVOKE
SET SHOW
对象:DATABASE SCHEMA FUNCTION TRIGGER TABLE SEQUENCE FOREIGN_SERVER FOREIGN_TABLE TABLESPACE ROLE/USER INDEX VIEW DATA_SOURCE | +| **DML** | 操作:ALL COPY DEALLOCATE DELETE EXECUTE REINDEX INSERT
PREPARE SELECT TRUNCATE UPDATE | + +## 特性增强 + +无。 + +## 特性约束 + +- 统一审计策略需要由具备POLADMIN或SYSADMIN属性的用户或初始用户创建,普通用户无访问安全策略系统表和系统视图的权限。 +- 统一审计策略语法要么针对DDL行为,要么针对DML语法行为,同一个审计策略不可同时包含DDL和DML行为;统一审计策略目前支持最多设置98个。 +- 统一审计监控用户通过客户端执行的SQL语句,而不会记录数据库内部SQL语句。 +- 同一个审计策略下,相同资源标签可以绑定不同的审计行为,相同行为可以绑定不同的资源标签, 操作”ALL”类型包括DDL或者DML下支持的所有操作。 +- 同一个资源标签可以关联不同的统一审计策略,统一审计会按照SQL语句匹配的策略依次打印审计信息。 +- 统一审计策略的审计日志单独记录,暂不提供可视化查询接口,整个日志依赖于操作系统自带rsyslog服务,通过配置完成日志归档。 +- 在云服务场景下,日志需要存储在OBS服务中;在混合云场景下,可部署Elastic Search进行日志收集和可视化处理。 +- FILTER中的APP项建议仅在同一信任域内使用,由于客户端不可避免的可能出现伪造名称的情况,该选项使用时需要与客户端联合形成一套安全机制,减少误用风险。一般情况下不建议使用,使用时需要注意客户端仿冒的风险。 +- FILTER中的IP地址以ipv4为例支持如下格式。 + +| ip地址格式 | 示例 | +| ---------- | ------------------------ | +| 单ip | 127.0.0.1 | +| 掩码表示ip | 127.0.0.1\|255.255.255.0 | +| cidr表示ip | 127.0.0.1/24 | +| ip区间 | 127.0.0.1-127.0.0.5 | + +## 依赖关系 + +在公有云服务场景下,依赖OSS服务或OBS服务存储日志。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/9-dynamic-data-anonymization.md b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/9-dynamic-data-anonymization.md new file mode 100644 index 00000000..7e5f10a0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/database-security/9-dynamic-data-anonymization.md @@ -0,0 +1,93 @@ +--- +title: 动态数据脱敏机制 +summary: 动态数据脱敏机制 +author: Guo Huan +date: 2022-05-07 +--- + +# 动态数据脱敏机制 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +数据脱敏是行之有效的数据库隐私保护方案之一,可以在一定程度上限制非授权用户对隐私数据的窥探。动态数据脱敏机制是一种通过定制化制定脱敏策略从而实现对隐私数据保护的一种技术,可以有效地在保留原始数据的前提下解决非授权用户对敏感信息的访问问题。当管理员指定待脱敏对象和定制数据脱敏策略后,用户所查询的数据库资源如果关联到对应的脱敏策略时,则会根据用户身份和脱敏策略进行数据脱敏,从而限制非授权用户对隐私数据的访问。 + +## 客户价值 + +数据隐私保护是数据库安全所需要具备的安全能力之一,可以在一定程度上限制非授权用户对隐私数据的访问,保证隐私数据安全。动态数据脱敏机制可以通过配置脱敏策略实现对指定数据库资源信息的隐私保护,另一方面,脱敏策略的配置也具有一定的灵活性,可以仅针对特定用户场景实现有针对性的隐私保护能力。 + +## 特性描述 + +动态数据脱敏机制基于资源标签进行脱敏策略的定制化,可根据实际场景选择特定的脱敏方式,也可以针对某些特定用户制定脱敏策略。一个完整的脱敏策略创建的SQL语法如下所示: + +```sql +CREATE RESOURCE LABEL label_for_creditcard ADD COLUMN(user1.table1.creditcard); +CREATE RESOURCE LABEL label_for_name ADD COLUMN(user1.table1.name); +CREATE MASKING POLICY msk_creditcard creditcardmasking ON LABEL(label_for_creditcard); +CREATE MASKING POLICY msk_name randommasking ON LABEL(label_for_name) FILTER ON IP(local), ROLES(dev); +``` + +其中,label_for_creditcard和msk_name为本轮计划脱敏的资源标签,分别包含了两个列对象;creditcardmasking、randommasking为预置的脱敏函数;msk_creditcard定义了所有用户对label_for_creditcard标签所包含的资源访问时做creditcardmasking的脱敏策略,不区分访问源;msk_name定义了本地用户dev对label_for_name标签所包含的资源访问时做randommasking的脱敏策略;当不指定FILTER对象时则表示对所有用户生效,否则仅对标识场景的用户生效。 + +当前,预置的脱敏函数包括: + +| 脱敏函数名 | 示例 | +| ----------------- | ------------------------------------------------------------ | +| creditcardmasking | '4880-9898-4545-2525' 将会被脱敏为 'xxxx-xxxx-xxxx-2525',该函数仅对后4位之前的数字进行脱敏 | +| basicemailmasking | 'abcd@gmail.com' 将会被脱敏为 'xxxx@gmail.com', 对出现第一个'@'之前的文本进行脱敏 | +| fullemailmasking | 'abcd@gmail.com' 将会被脱敏为 'xxxx@xxxxx.com',对出现最后一个'.'之前的文本(除'@'符外)进行脱敏 | +| alldigitsmasking | 'alex123alex' 将会被脱敏为 'alex000alex', 仅对文本中的数字进行脱敏 | +| shufflemasking | 'hello word' 将会被随机打乱顺序脱敏为 'hlwoeor dl', 该函数通过字符乱序排列的方式实现,属于弱脱敏函数,语义较强的字符串不建议使用该函数脱敏。 | +| randommasking | 'hello word' 将会被脱敏为 'ad5f5ghdf5',将文本按字符随机脱敏 | +| maskall | '4880-9898-4545-2525' 将会被脱敏为 'xxxxxxxxxxxxxxxxxxx' | + +每个脱敏函数规格如下: + +| 脱敏函数名 | 支持的数据类型 | +| ----------------- | ------------------------------------------------------------ | +| creditcardmasking | BPCHAR, VARCHAR, NVARCHAR, TEXT(注:仅针对信用卡格式的文本类数据) | +| basicemailmasking | BPCHAR, VARCHAR, NVARCHAR, TEXT(注:仅针对email格式的文本类型数据) | +| fullemailmasking | BPCHAR, VARCHAR, NVARCHAR, TEXT(注:仅针对email格式的文本类型数据) | +| alldigitsmasking | BPCHAR, VARCHAR, NVARCHAR, TEXT(注:仅针对包含数字的文本类型数据) | +| shufflemasking | BPCHAR, VARCHAR, NVARCHAR, TEXT(注:仅针对文本类型数据) | +| randommasking | BPCHAR, VARCHAR, NVARCHAR, TEXT(注:仅针对文本类型数据) | +| maskall | BOOL, RELTIME, TIME, TIMETZ, INTERVAL, TIMESTAMP, TIMESTAMPTZ, SMALLDATETIME, ABSTIME,TEXT, BPCHAR, VARCHAR, NVARCHAR2, NAME, INT8, INT4, INT2, INT1, NUMRIC, FLOAT4, FLOAT8, CASH | + +对于不支持的数据类型,默认使用maskall函数进行数据脱敏,若数据类型不属于maskall支持的数据类型则全部使用数字0进行脱敏,如果脱敏列涉及隐式转换,则结果以隐式转换后的数据类型为基础进行脱敏。另外需要说明的是,如果脱敏策略应用到数据列并生效,此时对该列数据的操作将以脱敏后的结果为基础而进行。 + +动态数据脱敏适用于和实际业务紧密相关的场景,根据业务需要为用户提供合理的脱敏查询接口,以避免通过撞库而获取原始数据。 + +## 特性增强 + +无。 + +## 特性约束 + +- 动态数据脱敏策略需要由具备POLADMIN或SYSADMIN属性的用户或初始用户创建,普通用户没有访问安全策略系统表和系统视图的权限。 +- 动态数据脱敏只在配置了脱敏策略的数据表上生效,而审计日志不在脱敏策略的生效范围内。 +- 在一个脱敏策略中,对于同一个资源标签仅可指定一种脱敏方式,不可重复指定。 +- 不允许多个脱敏策略对同一个资源标签进行脱敏,除以下脱敏场景外:使用FILTER指定策略生效的用户场景,包含相同资源标签的脱敏策略间FILTER生效场景无交集,此时可以根据用户场景明确辨别资源标签被哪种策略脱敏。 +- Filter中的APP项建议仅在同一信任域内使用,由于客户端不可避免的可能出现伪造名称的情况,该选项使用时需要与客户端联合形成一套安全机制,减少误用风险。一般情况下不建议使用,使用时需要注意客户端仿冒的风险。 +- 对于带有query子句的INSERT或MERGE INTO操作,如果源表中包含脱敏列,则上述两种操作中插入或更新的结果为脱敏后的值,且不可还原。 +- 在内置安全策略开关开启的情况下,执行ALTER TABLE EXCHANGE PARTITION操作的源表若在脱敏列则执行失败。 +- 对于设置了动态数据脱敏策略的表,需要谨慎授予其他用户对该表的trigger权限,以免其他用户利用触发器绕过脱敏策略。 +- 最多支持创建98个动态数据脱敏策略。 +- 仅支持使用上述七种预置脱敏策略。 +- 仅支持对只包含COLUMN属性的资源标签做脱敏。 +- 仅支持对基本表的列进行数据脱敏。 +- 仅支持对SELECT查询到的数据进行脱敏。 +- FILTER中的IP地址以ipv4为例支持如下格式。 + +| ip地址格式 | 示例 | +| ---------- | ------------------------ | +| 单ip | 127.0.0.1 | +| 掩码表示ip | 127.0.0.1/255.255.255.0 | +| cidr表示ip | 127.0.0.1/24 | +| ip区间 | 127.0.0.1-127.0.0.5 | + +## 依赖关系 + +无。 diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/1-support-for-functions-and-stored-procedures.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/1-support-for-functions-and-stored-procedures.md new file mode 100644 index 00000000..3fc4637b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/1-support-for-functions-and-stored-procedures.md @@ -0,0 +1,38 @@ +--- +title: 函数及存储过程支持 +summary: 函数及存储过程支持 +author: Guo Huan +date: 2022-05-07 +--- + +# 函数及存储过程支持 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +函数和存储过程是数据库中的一种重要对象,主要功能将用户特定功能的SQL语句集进行封装,并方便调用。 + +## 客户价值 + +1. 允许客户模块化程序设计,对SQL语句集进行封装,调用方便。 +2. 存储过程会进行编译缓存,可以提升用户执行SQL语句集的速度。 +3. 系统管理员通过限制执行某一存储过程的权限,能够实现对相应的数据的访问权限的限制,避免了非授权用户对数据的访问,保证了数据的安全。 + +## 特性描述 + +MogDB支持SQL标准中的函数及存储过程,其中存储过程兼容了部分主流数据库存储过程的语法,增强了存储过程的易用性。 + +## 特性增强 + +支持PL/PGSQL单步调试功能。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/10-autonomous-transaction.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/10-autonomous-transaction.md new file mode 100644 index 00000000..a6e3b6b2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/10-autonomous-transaction.md @@ -0,0 +1,44 @@ +--- +title: 自治事务 +summary: 自治事务 +author: Guo Huan +date: 2022-05-07 +--- + +# 自治事务 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +子事务的提交不受主事务提交或回滚影响的一类事务。 + +## 客户价值 + +满足客户多样化使用场景。 + +## 特性描述 + +自治事务为在主事务执行过程中,以独立的事务上下文执行指定的某一类SQL语句,其commit和rollback不受主事务commit和rollback的影响。 + +用户自定义函数、存储过程支持自治事务。 + +典型使用场景是,用一个表记录主事务执行过程中的操作信息,并且在主事务失败回退的时候,表中记录的操作信息不予回退。 + +## 特性增强 + +无。 + +## 特性约束 + +- 触发器函数不支持自治事务。 +- 函数或者存储过程的自治事务块中,静态sql语句不支持变量传递。 +- 自治事务不支持执行嵌套。 +- 包含自治事务的函数,不支持参数传递的返回值。 +- 包含自治事务的存储过程/函数,不支持exception异常处理。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/11-global-temporary-table.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/11-global-temporary-table.md new file mode 100644 index 00000000..0ed9d524 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/11-global-temporary-table.md @@ -0,0 +1,45 @@ +--- +title: 全局临时表 +summary: 全局临时表 +author: Guo Huan +date: 2022-05-07 +--- + +# 全局临时表 + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +临时表顾名思义是不保证持久化的表,其生命周期一般跟session或者事务绑定,可以方便用于表达处理过程中的一些临时数据存放,加速查询。 + +## 客户价值 + +提升临时表的表达能力和易用性。 + +## 特性描述 + +全局临时表的元数据对所有会话可见,会话结束后元数据继续存在。会话与会话之间的用户数据、索引和统计信息相互隔离,每个会话只能看到和更改自己提交的数据。 + +全局临时表有两种模式:一种是基于会话级别的(ON COMMIT PRESERVE ROWS),当会话结束时自动清空用户数据;一种是基于事务级别的(ON COMMIT DELETE ROWS), 当执行commit或rollback时自动清空用户数据。建表时如果没有指定ON COMMIT选项,则缺省为会话级别。与本地临时表不同,全局临时表建表时可以指定非pg_temp_开头的schema。 + +## 特性增强 + +在本地临时表的基础上增加了全局临时表的处理。 + +## 特性约束 + +- 不支持并行扫描 +- 不支持temp tablespace +- 不支持partition +- 不支持GIST索引 +- 不支持User-defined统计信息pg_statistic_ext +- 不支持ON COMMIT DROP +- 不支持hash bucket 聚簇存储 +- 不支持列存 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/12-pseudocolumn-rownum.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/12-pseudocolumn-rownum.md new file mode 100644 index 00000000..4fcd223c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/12-pseudocolumn-rownum.md @@ -0,0 +1,43 @@ +--- +title: 伪列ROWNUM +summary: 伪列ROWNUM +author: Guo Huan +date: 2022-05-07 +--- + +# 伪列ROWNUM + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +ROWNUM为查询出来的每一行记录生成一个序号,从1开始依次递增且不会重复。 + +## 客户价值 + +- 兼容Oracle特性,方便数据库迁移。 +- 与LIMIT特性类似,能够筛选出结果集的前n条记录。 + +## 特性描述 + +ROWNUM(伪列),用于对SQL查询中符合条件的记录进行顺序标注。查询结果第一行ROWNUM为1,第二行为2,依次类推,第n行为n。通常用来筛选出查询结果集中的前n行数据,与MogDB中LIMIT功能类似。 + +## 特性增强 + +在内部执行时,优化器会将ROWNUM重写成LIMIT去执行,加快执行速率。 + +## 特性约束 + +- ROWNUM是伪列,不可作为别名,以免SQL语句出现歧义; +- 创建索引时不可使用ROWNUM。例如:create index index_name on table(rownum); +- 创建表时default值不可为ROWNUM。例如:create table table_name(id int default rownum); +- Where子句中不可使用rownum的别名。例如:select rownum rn from table where rn < 5; +- 在插入数据时不可使用ROWNUM。例如:insert into table values(rownum,’blue’); +- 不可在无表查询中使用ROWNUM。例如:select * from (values(rownum,1)), x(a,b); +- 若 having 子句中含有ROWNUM(且不在聚合函数中)时,group by子句中必须含有ROWNUM(且不在聚合函数中)。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/13-stored-procedure-debugging.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/13-stored-procedure-debugging.md new file mode 100644 index 00000000..a3ed85ae --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/13-stored-procedure-debugging.md @@ -0,0 +1,38 @@ +--- +title: 支持存储过程调试 +summary: 支持存储过程调试 +author: Guo Huan +date: 2022-05-07 +--- + +# 支持存储过程调试 + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +提供调试存储过程的一组API,可以进行断点调试、变量打印等对存储过程的调试功能。 + +## 客户价值 + +提升客户基于MogDB开发存储过程的开发体验。 + +## 特性描述 + +存储过程是数据库中的一种重要对象,主要功能将用户特定功能的SQL语句集进行封装,并方便调用。一个存储过程中往往包含着众多的sql以及过程化的执行结构,根据所需业务的规模大小而定。然而书写一个大的存储过程,往往会伴随着逻辑BUG,仅通过执行存储过程观察结果很难甚至无法发现其中存在的问题,因此需要一个调试工具。 + +存储过程调试工具,提供一组调试接口,可以使存储过程单步执行,在执行过程中设置断点、打印变量等,便于SQL开发者能够及时便捷的发现错误、修正错误,更高效、更快捷、高质量的进行功能开发。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/14-jdbc-client-load-balancing-and-readwrite-isolation.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/14-jdbc-client-load-balancing-and-readwrite-isolation.md new file mode 100644 index 00000000..aeb30b11 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/14-jdbc-client-load-balancing-and-readwrite-isolation.md @@ -0,0 +1,36 @@ +--- +title: JDBC客户端负载均衡与读写分离 +summary: JDBC客户端负载均衡与读写分离 +author: Guo Huan +date: 2022-05-07 +--- + +# JDBC客户端负载均衡与读写分离 + +## 可获得性 + +本特性自MogDB 2.1.0 版本开始引入。 + +## 特性简介 + +JDBC 客户端提供负载均衡与读写分离能力。 + +## 客户价值 + +可从JDBC客户端测配置负载均衡与读写分离。 + +## 特性描述 + +客户端多节点IP+Port配置,适应多AZ间高可用切换、适应异地容灾切换。支持连接级读写分离配置。支持优先连接只读节点。多个只读节点连接分布均衡。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/15-in-place-update-storage-engine.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/15-in-place-update-storage-engine.md new file mode 100644 index 00000000..97bea005 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/15-in-place-update-storage-engine.md @@ -0,0 +1,36 @@ +--- +title: In-place Update存储引擎 +summary: In-place Update存储引擎 +author: Guo Huan +date: 2022-05-07 +--- + +# In-place Update存储引擎 + +## 可获得性 + +本特性自MogDB 2.1.0 版本开始引入。 + +## 特性简介 + +In-place Update存储引擎(原地更新),是MogDB内核新增的一种存储模式。MogDB内核此前的版本使用的行存储引擎是Append Update(追加更新)模式。追加更新对于业务中的增、删以及HOT(HeapOnly Tuple) Update(即同一页面内更新)有很好的表现,但对于跨数据页面的非HOT UPDATE场景,垃圾回收不够高效,Ustore存储引擎可很好解决上述问题。 + +## 客户价值 + +In-place Update存储引擎可有效的降低多次更新元组后占用存储空间问题。 + +## 特性描述 + +新增的In-place update存储引擎很好的解决了Append update存储引擎空间膨胀,元组较大的劣势,高效回滚段的设计是In-place update存储引擎的基础。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/16-publication-subscription.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/16-publication-subscription.md new file mode 100644 index 00000000..0597c330 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/16-publication-subscription.md @@ -0,0 +1,52 @@ +--- +title: 发布订阅 +summary: 发布订阅 +author: Guo Huan +date: 2022-05-10 +--- + +# 发布订阅 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +发布订阅基于逻辑复制实现,其中有一个或者更多订阅者订阅一个发布者节点上的一个或者更多发布。订阅者从它们所订阅的发布拉取数据。实现集群间的数据实时同步。 + +## 客户价值 + +发布订阅的典型使用场景是: + +- 在一个数据库或者一个数据库的子集中发生更改时,把增量的改变发送给订阅者。 +- 在更改到达订阅者时引发触发器。 +- 把多个数据库联合到单一数据库中(例如用于分析目的)。 + +## 特性描述 + +发布者上的更改会被实时发送给订阅者。订阅者以与发布者相同的顺序应用那些数据,这样在一个订阅中能够保证发布的事务一致性。这种数据复制的方法有时候也被称为事务性复制。 + +订阅者数据库的行为与任何其他MogDB实例相同,并且可以被用作其他数据库的发布者,只需要定义它自己的发布。当订阅者被应用当作只读时,单一的订阅中不会有冲突。在另一方面,如果应用或者对相同表集合的订阅者执行了其他的写动作,冲突可能会发生。 + +## 特性增强 + +无。 + +## 特性约束 + +发布订阅基于逻辑复制实现,继承所有逻辑复制的限制,同时发布订阅还有下列额外的限制或者缺失的功能。 + +- 数据库模式和DDL命令不会被复制。初始模式可以手工使用gs_dump --schema-only进行拷贝。后续的模式改变需要手工保持同步。 +- 序列数据不被复制。后台由序列支撑的serial或者标识列中的数据当然将被作为表的一部分复制,但是序列本身在订阅者上仍将显示开始值。如果订阅者被用作一个只读数据库,那么这通常不会是什么问题。不过,如果订阅者数据库预期有某种转换或者容错,那么序列需要被更新到最后的值,要么通过从发布者拷贝当前数据的防范(也许使用gs_dump),要么从表本身决定一个足够高的值。 +- 只有表支持复制,包括分区表。试图复制其他类型的关系,例如视图、物化视图或外部表,将会导致错误。 +- 同一数据库内的多个订阅不应当订阅内容重复的发布(指发布相同的表),否则会产生数据重复或者主键冲突。 +- 如果被发布的表中包含不支持btree/hash索引的数据类型(如地理类型等),那么该表需要有主键,才能成功的复制UPDATE/DELETE操作到订阅端。否则复制会失败,同时订阅端会出现“FATAL: could not identify an equality operator for type xx”的日志。 + +## 依赖关系 + +发布订阅依赖逻辑复制功能。 + +## 相关页面 + +[CREATE PUBLICATION](../../reference-guide/sql-syntax/CREATE-PUBLICATION.md)、[CREATE SUBSCRIPTION](../../reference-guide/sql-syntax/CREATE-SUBSCRIPTION.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/17-foreign-key-lock-enhancement.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/17-foreign-key-lock-enhancement.md new file mode 100644 index 00000000..32ef8513 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/17-foreign-key-lock-enhancement.md @@ -0,0 +1,45 @@ +--- +title: 外键锁增强 +summary: 外键锁增强 +author: Guo Huan +date: 2022-05-10 +--- + +# 外键锁增强 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +新增两类行锁,由share和update锁扩展到key share、share、no key update和update。非主键的更新获取的是no key update锁,外键触发器获取的行锁为key share锁,这两种类型的锁互不冲突,以此提升了外键锁的并发性。 + +## 客户价值 + +绝大多数的表更新操作为非主键的更新,该特性有效地减少了有外键约束的场景下多并发更新的阻塞,提升效率。 + +## 特性描述 + +当对父表一行元组的非主键列进行更新时,获取no key update锁;对子表对应元组的更新或插入,触发外键触发器,获取父表元组的key share锁。两者互不阻塞。 + +由于增加了互不冲突的行锁,多事务不再只由share锁组成,而有多种不同行锁的组合方式,依据如下的冲突表。 + +| 锁模式 | key share | share | no key update | update | +| ------------- | --------- | ----- | ------------- | ------ | +| key share | | | | X | +| share | | | X | X | +| no key update | | X | X | X | +| update | X | X | X | X | + +## 特性增强 + +无。 + +## 特性约束 + +- 新增的行锁暂不支持ustore表 + +## 依赖关系 + +无 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/18-data-compression-in-oltp-scenarios.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/18-data-compression-in-oltp-scenarios.md new file mode 100644 index 00000000..ea597e61 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/18-data-compression-in-oltp-scenarios.md @@ -0,0 +1,29 @@ +--- +title: 支持OLTP场景数据压缩 +summary: 支持OLTP场景数据压缩 +author: Guo Huan +date: 2022-05-10 +--- + +# 支持OLTP场景数据压缩 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +支持OLTP场景行存数据压缩,提供通用压缩算法,通过对数据页的透明页压缩和维护页面存储位置的方式,做到高压缩、高性能。磁盘持久化用2个文件存储,分别是压缩地址文件(扩展名.pca)和压缩数据文件(扩展名.pcd)。 + +## 客户价值 + +典型使用场景是:希望降低数据库磁盘的空间需求。 + +## 特性描述 + +新增的支持OLTP场景数据压缩可以降低行表、索引数据的磁盘存储空间需求,在IO密集的数据库系统,可以有一定的性能提升。 + +## 特性约束 + +- 仅支持行存表、BTree索引,不可以在USTORE、段页式存储引擎上使用。 +- 压缩表索引文件采用mmap访问,需要基于压缩表文件数量,设置足够的max_map_count。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/19-transaction-async-submit.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/19-transaction-async-submit.md new file mode 100644 index 00000000..31787383 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/19-transaction-async-submit.md @@ -0,0 +1,30 @@ +--- +title: 事务异步提交 +summary: 事务异步提交 +author: Guo Huan +date: 2022-06-13 +--- + +# 事务异步提交 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +在MogDB的线程池模式下为每个线程组增加了committer线程,当事务提交过程中等待日志刷盘的时候将session挂起,交由committer线程在日志刷盘完成之后继续提交事务,而原worker线程在该session挂起之后可以去处理其他待处理的session。 + +## 客户价值 + +在TP场景中,对高并发下事务处理的性能有较高的需求。然而MogDB中事务提交的过程中需要同步等待日志落盘,这一期间的worker线程处于空闲状态,并不能被利用去处理其他的事务。虽然在MogDB中有“synchronous_commit=off”的实现,但该实现并不能保证数据库中途崩溃之后数据的完整性。 + +本特性能够实现真正意义上的事务异步提交,在保证数据库可靠性的前提下更加充分利用CPU,提升高并发场景下事务处理处理能力,尤其在小查询的增删改操作上会有明显的体现。 + +## 特性约束 + +- 该功能仅在线程池模式下打开有效,非线程池模式下不支持事务异步提交。即设置“enable_thread_pool = on”和“synchronous_commit”不为“off”。 + +## 相关页面 + +[GS_ASYNC_SUBMIT_SESSIONS_STATUS](../../reference-guide/system-catalogs-and-system-views/system-views/GS_ASYNC_SUBMIT_SESSIONS_STATUS.md)、[async_submit](../../reference-guide/guc-parameters/20-MogDB-transaction.md#async_submit)、[LOCAL_THREADPOOL_STATUS](../../reference-guide/schema/DBE_PERF/session-thread/LOCAL_THREADPOOL_STATUS.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/2-sql-hints.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/2-sql-hints.md new file mode 100644 index 00000000..18cfa0b9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/2-sql-hints.md @@ -0,0 +1,40 @@ +--- +title: 支持SQL hint +summary: 支持SQL hint +author: Guo Huan +date: 2022-05-07 +--- + +# 支持SQL hint + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +支持SQL hint影响执行计划生成。 + +## 客户价值 + +提升SQL查询性能。 + +## 特性描述 + +Plan Hint为用户提供了直接影响执行计划生成的手段,用户可以通过指定join顺序,join、stream、scan方法,指定结果行数,指定重分布过程中的倾斜信息等多个手段来进行执行计划的调优,以提升查询的性能。 + +## 特性增强 + +支持planhint设置session级优化器参数。 + +支持指定子查询不展开。 + +支持单query禁用gpc。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/20-copy-import-optimization.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/20-copy-import-optimization.md new file mode 100644 index 00000000..40913133 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/20-copy-import-optimization.md @@ -0,0 +1,95 @@ +--- +title: COPY导入优化 +summary: COPY导入优化 +author: Guo Huan +date: 2022-06-16 +--- + +# COPY导入优化 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +COPY是使用较多的导入用户表数据的方式,本特性通过利用现代CPU的SIMD特性来提升COPY在解析阶段的性能,从而提升COPY的性能,提升导入的速度。 + +COPY从文件中导入数据的时候在解析阶段查找分隔符以及在判断CSV/TEXT解析出的数据是否合法的时候,理论上都是字符串比较操作,可以利用SIMD特性将现有一次一个字符比较转换成一次比较多个字符,从而减少分支判断次数提升性能。 + +## 客户价值 + +利用SIMD指令针对COPY解析过程中的行列分隔符查找做优化。本特性的最终用户为普通客户群体,如数据库DBA,软件开发人员等。COPY性能提升为10%-30%。 + +| 数据总条数 | **100000000**(1亿) | +| ---------------- | -------------------- | +| **数据总大小** | **24GB** | +| **平均性能提升** | **12.29%** | + +测试结果如下: + +| 测试次序 | 未使用SIMD特性耗时(秒) | 使用SIMD特性耗时(秒) | +| ---------- | ------------------------ | ---------------------- | +| 第一次测试 | 761.01 | 671.05 | +| 第二次测试 | 747.06 | 662.60 | +| 第三次测试 | 770.22 | 663.03 | +| 第四次测试 | 747.940 | 674.03 | +| 第五次测试 | 787.22 | 674.13 | +| 平均耗时 | 762.69 | 668.97 | + +## 特性约束 + +- 只支持X86架构的机器,只支持text和csv文件,且如下情况不支持:转义字符、escape以及quote,null值替换以及自定义列分隔符; + +- 因为该字符串比较指令值是SSE4.2才开始支持,所以只有支持SSE4.2的X86才可以使用该优化。 + +可以使用如下命令来判断机器是否支持SSE4.2指令集(以root或者omm用户登录都可以): + +```shell +--显示为SSE 4.2 supported表示支持 +[omm3@hostname ~]$ grep -q sse4_2 /proc/cpuinfo && echo "SSE 4.2 supported" || echo "SSE 4.2 not supported" +SSE 4.2 supported + +--显示为SSE 4.2 supported表示不支持 +[xxxx@hostname ~]$ grep -q sse4_2 /proc/cpuinfo && echo "SSE 4.2 supported" || echo "SSE 4.2 not supported" +SSE 4.2 not supported +``` + +可以使用以下命令开启或关闭enable_sse42特性 + +登录数据库 + +```shell +[omm3@hostname ~]$ gsql -d postgres -p18000 +gsql ((MogDB 3.0.0 build 945141ad) compiled at 2022-05-28 16:14:02 commit 0 last mr ) +Non-SSL connection (SSL connection is recommended when requiring high-security) +Type "help" for help. +``` + +开启enable_sse42特性 + +```sql +MogDB=# set enable_sse42 to on; +SET +MogDB=# show enable_sse42; +enable_sse42 +-------------- + on +(1 row) +``` + +关闭enable_sse42特性 + +```sql +MogDB=# set enable_sse42 to off; +SET +MogDB=# show enable_sse42; +enable_sse42 +-------------- +off +(1 row) +``` + +## 相关页面 + +[COPY](../../reference-guide/sql-syntax/COPY.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/21-dynamic-partition-pruning.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/21-dynamic-partition-pruning.md new file mode 100644 index 00000000..d22c0d4f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/21-dynamic-partition-pruning.md @@ -0,0 +1,32 @@ +--- +title: 动态分区裁剪 +summary: 动态分区裁剪 +author: Guo Huan +date: 2022-06-17 +--- + +# 动态分区裁剪 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +本特性主要实现如下4个功能: + +1. 支持NEST LOOP进行分区裁剪。 + +2. 支持绑定变量进行分区裁剪。 + +3. 支持子查询进行分区裁剪。 + +4. 支持通过EXPLAIN ANALYZE查看动态分区裁剪结果。 + +## 客户价值 + +本特性主要对分区裁剪特性进行优化,引入动态分区裁剪,同时支持通过EXPLAIN ANALYZE查看分区裁剪结果。在SQL执行阶段裁剪掉不需要的分区,再扫描分区表,从而提升分区表的查询性能。 + +## 相关页面 + +[静态分区裁剪](../../developer-guide/partition-management/partition-pruning/static-partition-pruning.md)、[动态分区裁剪](../../developer-guide/partition-management/partition-pruning/dynamic-partition-pruning.md) diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/22-sql-running-status-observation.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/22-sql-running-status-observation.md new file mode 100644 index 00000000..d11342bc --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/22-sql-running-status-observation.md @@ -0,0 +1,107 @@ +--- +title: SQL运行状态观测 +summary: SQL运行状态观测 +author: Guo Huan +date: 2022-06-17 +--- + +# SQL运行状态观测 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +采样线程默认1s采样一次,可通过guc参数asp_sample_interval控制,内存中最多采样100000行数据,通过asp_sample_num控制,到达上限就会刷新到磁盘上。 + +## 客户价值 + +当发现某条SQL语句存在性能瓶颈,且无法在采样视图中查询到该SQL每个算子的执行情况时,可以通过plan_node_id定位性能问题。 + +算子:SQL语句执行过程中各个步骤的具体动作(例如:SELECT、SUM、WHERE、Group By、Having、Order By、Limit等) + +## 特性描述 + +在[dbe_perf.local_active_session](../../reference-guide/schema/DBE_PERF/session-thread/LOCAL_ACTIVE_SESSION.md)和[GS_ASP](../../reference-guide/system-catalogs-and-system-views/system-catalogs/GS_ASP.md)中新增一列plan_node_id来记录SQL语句每个算子操作的执行情况。 + +现有的监控级别由guc参数[resource_track_level](../../reference-guide/guc-parameters/13-load-management.md#resource_track_level)控制,该参数按照级别存在三个值,分别是: + +- none:不开启资源记录功能; + +- query:开启query级别资源记录功能; + +- operator:开启query级别和算子级别资源记录功能, + +所以只有当将resource_track_level设成operator的时候才会对SQL语句每个算子操作进行采样。 + +MogDB启动后会启动一个后台worker采样线程,为避免浪费资源,该采样线程不会时刻采样,而是每隔一个采样周期对MogDB进行采样,收集MogDB当时的运行快照保存到内存中,查询视图dbe_perf.local_active_session可以查询到实时的采样信息,该采样周期由guc参数[asp_sample_interval](../../reference-guide/guc-parameters/27-system-performance-snapshot.md#asp_sample_interval)控制,默认采样周期为1s,MogDB每在内存中采样100000行(由guc参数[asp_sample_num](../../reference-guide/guc-parameters/27-system-performance-snapshot.md#asp_sample_num)控制)会将内存中的采样数据刷新到GS_ASP表中以供历史查询,只有语句执行时间大于采样时间,才会被采样线程收集到运行信息。 + +## 使用场景 + +1. 首先在session1中创建表test,并执行插入操作: + + ```sql + MogDB=# create table test(c1 int); + CREATE TABLE + MogDB=# insert into test select generate_series(1, 1000000000); + ``` + +2. 在session2中,从活跃会话视图中查询出该SQL的query_id + + ```sql + MogDB=# select query,query_id from pg_stat_activity where query like 'insert into test select%'; + query | query_id + -----------------------------------------------------------+----------------- + insert into test select generate_series(1, 100000000000); | 562949953421368 + (1 row) + ``` + +3. 在session2中,根据该query_id从活跃作业管理视图中查询出该语句的带plan_node_id的执行计划(该语句执行cost需要大于guc值**resource_track_cost**才会被记录到该视图中,该guc参数默认值为100000,session级别可更新,所以为了方便测试,可在测试中将该值改成10) + + Set resource_track_cost=10; + + ```sql + MogDB=# select query_plan from dbe_perf.statement_complex_runtime where queryid = 562949953421368; + query_plan + ---------------------------------------------------------------------------- + Coordinator Name: datanode1 + + 1 | Insert on test (cost=0.00..17.51 rows=1000 width=8) + + 2 | -> Subquery Scan on "*SELECT*" (cost=0.00..17.51 rows=1000 width=8) + + 3 | -> Result (cost=0.00..5.01 rows=1000 width=0) + + + + (1 row) + ``` + +4. 在session2中,根据query_id从采样视图dbe_perf.local_active_session中查询出该语句的采样情况,结合上面查询的执行计划做性能分析。 + + ```sql + MogDB=# select plan_node_id, count(plan_node_id) from dbe_perf.local_active_session where query_id = 562949953421368 group by plan_node_id; + plan_node_id | count + --------------+------- + 3 | 12 + 1 | 366 + 2 | 2 + (3 rows) + ``` + +5. 在session2中执行,当内存数据到达上限值(由guc参数**asp_sample_num**控制)的时候,则会将现有内存的采样数据刷新到gs_asp表中,刷盘后查询gs_asp表也会查到该语句的算子采样的数据。 + + ```sql + MogDB=# select plan_node_id, count(plan_node_id) from gs_asp where query_id = 562949953421368 group by plan_node_id; + plan_node_id | count + --------------+------- + 3 | 19 + 1 | 582 + 2 | 3 + + (3 rows) + ``` + +## 结论 + +当发现`insert into test select generate_series(1, 1000000000)`存在性能瓶颈,通过以上的步骤定位发现,insert操作在整个SQL语句执行过程中被采样的数值最高( plan_node_id =1 ,count=366),可以对其进行优化。 + +## 相关页面 + +[GS_ASP](../../reference-guide/system-catalogs-and-system-views/system-catalogs/GS_ASP.md)、[LOCAL_ACTIVE_SESSION](../../reference-guide/schema/DBE_PERF/session-thread/LOCAL_ACTIVE_SESSION.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/23-index-creation-parallel-control.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/23-index-creation-parallel-control.md new file mode 100644 index 00000000..a517cedd --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/23-index-creation-parallel-control.md @@ -0,0 +1,28 @@ +--- +title: 索引创建并行控制 +summary: 索引创建并行控制 +author: Guo Huan +date: 2022-06-17 +--- + +# 索引创建并行控制 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +本特性支持直接在索引创建语句中指定并行度,更加有效地利用资源,同时提高使用灵活性。 + +## 客户价值 + +本特性在创建索引的语法中增加指定并行度的选项,便于DBA及交付测试人员从语法层面实现对索引创建并发度的控制,达到最优执行效果。 + +## 特性描述 + +在进行索引创建的时候增加parallel语法,来控制索引创建的并行度。 + +## 相关页面 + +[CREATE INDEX](../../reference-guide/sql-syntax/CREATE-INDEX.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/24-brin-index.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/24-brin-index.md new file mode 100644 index 00000000..d34be1fa --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/24-brin-index.md @@ -0,0 +1,257 @@ +--- +title: BRIN索引 +summary: BRIN索引 +author: Guo Huan +date: 2022-06-20 +--- + +# BRIN索引 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +MogDB 3.0.0版本新增BRIN索引特性。 + +BRIN索引即block range index块范围索引。和其他索引不同,BRIN索引可以实现快速排除不满足查询条件的行。 + +## 客户价值 + +- 顺序扫描会很快,则针对大表的统计型SQL性能会大幅提升。 +- 创建索引的速度非常快。 +- 索引占用的空间很小。 + +## 特性描述 + +BRIN索引即block range index块范围索引。和其他索引不同,BRIN索引的思想是快速排除不满足查询条件的行,而不是快速找到匹配的行。 + +BRIN索引的工作方式:表的块被划分成一些区间,索引存储了每个区间内的摘要信息(一般是min和max信息,对于空间数据还有一些其他信息)。如果要查询的列的值,不会落入这个区间的摘要信息中,那么就可以跳过这个区间,如果不能跳过,就需要扫描这个区间的所有行。 + +BRIN索引适合数据与物理位置有相关性的列。优化器使用这个值来从索引扫描和位图扫描中做选择。我们也可以使用它估计BRIN索引的适合程度。列的位置相关性越接近1,则列数据的相关性越强,越适合建BRIN索引。另外BRIN索引主要是为大表而设计的,相比于btree等索引,BRIN索引的数据量较小。 + +## 使用场景 + +### 创建BRIN索引 + +语法与创建B-树、哈希、GiST、SP-GiST、GIN的方式一致。 + +创建BRIN索引时可以指定参数pages_per_range 和 autosummarize。 + +pages_per_range:指定BRIN索引中每个range中包含多少个page,取值范围是 1 ~ 131072,如果不指定默认值是128。 + +autosummarize:指定是否对表中未建索引的数据页自动创建索引,默认值是 off。 + +```sql +CREATE INDEX brinidx ON tbbrin USING brin(i1,i2,i3) WITH (pages_per_range=64, autosummarize=off); +--在线创建 +CREATE INDEX CONCURRENTLY brinidx ON tbbrin USING brin(i1,i2,i3) WITH (pages_per_range=64); +``` + +### 重建BRIN索引 + +语法和重建创建B-树、哈希、GiST、SP-GiST、GIN的方式一致。 + +```sql +REINDEX INDEX brinidx ; +--在线重建索引 +REINDEX INDEX CONCURRENTLY brinidx ; +``` + +### 修改BRIN索引 + +BRIN支持修改pages_per_range和autosummarize参数,alter命令执行后,只是更新了元数据,需要执行reindex命令设置的参数才会生效。 + +示例: + +```sql +alter index idx set(pages_per_range=64); +reindex index idx; +``` + +### 查看BRIN索引的执行计划 + +示例: + +```sql +MogDB=# explain select * from example where id = 100; + QUERY PLAN +--------------------------------------------------------- + Bitmap Heap Scan on example (cost=15.88..486.21 rows=500 width=4) + Recheck Cond:(id = 100) + -> Bitmap Index Scan on idx (cost=0.00..15.75 rows=500 width=0) + Index Cond:(id =100) +(4 rows) +``` + +### BRIN索引手动更新 + +BRIN索引使用过程中可能出现部分数据页没有出现在索引中的情况,可以通过以下两种方式来手动更新BRIN索引。 + +- 对表执行vaccum操作; + +- 执行brin_summarize_new_values(oid)函数。入参为BRIN索引的oid,如果返回值为0则没有更新索引,返回1则索引已被更新。 + +示例: + +```sql +SELECT brin_summarize_new_values((select oid from pg_class where relname='brinidx')::oid); +``` + +可以通过以下操作来检查索引是否更新: + +- 从pg_class查看表的总块大小; + +- 根据brin_revmap_data查看已经建立索引的页号; + +- 计算前面2项的差值是否大于pages_per_range,若大于则说明索引需要更新。 + +### BRIN索引的autosummarize + +autosummarize 是否对表中未出现在索引中的数据页自动创建索引的开关。 + +可以通过以下步骤测试 autosummarize 是否失效: + +1. 更新表数据; + +2. 通过pg_stat_user_table查询表的last_autovacuum字段更新,例如: + + `````sql + MogDB=# select relname,last_vacuum,last_autovacuum from pg_stat_user_tables where relname = 'person'; + relname | last_vacuum | last_autovacuum + ---------+-------------------------------+----------------- + person | 2022-06-20 19:21:58.201214+08 | + (1 row) | + ````` + + 可以执行以下两条命令,来加快表的autovacuum频率: + + ```sql + ALTER TABLE example SET (autovacuum_vacuum_scale_factor = 0.0); + ALTER TABLE example SET (autovacuum_vacuum_threshold = 100); + ``` + +3. pg_stat_user_table表更新后,可以观察到索引数据的自动更新。 + + ```sql + MogDB=# select relname,last_vacuum,last_autovacuum from pg_stat_user_tables where relname = 'person'; + relname | last_vacuum | last_autovacuum + ---------+-------------------------------+----------------- + person | 2022-06-20 19:23:58.201214+08 | 2022-06-20 19:24:59.201214+08 + (1 row) + ``` + +### 通过pageinspect查看BRIN索引 + +对于表的BRIN索引,可以通过pageinspect查询页面数据。 + +pageinspect模块提供了允许查看数据库数据页面或索引页面内容的函数,这功能调试或问题定位很有帮助。pageinspect工具安装方式不变,安装时执行以下命令: + +````sql +create extension pageinspect; +```` + +pageinspect暂时只支持非分区表。 + +BRIN索引提供三个函数分别用于查询meta page、revmap_page和regular page中的数据: + +- brin_metapage_info(page bytea) returns record + + 返回有关BRIN索引元页的分类信息,其中第二个参数固定为0。例如: + + ```sql + MogDB=# SELECT * FROM brin_metapage_info(get_raw_page('brinidx', 0)); + magic | version | pagesperrange | lastrevmappage + ------------+---------+---------------+---------------- + 0xA8109CFA | 1 | 4 | 2 + ``` + +- brin_revmap_data(page bytea) returns setof tid + + 返回BRIN索引范围映射页面中的元组标识符列表。例如: + + ```sql + MogDB=# SELECT * FROM brin_revmap_data(get_raw_page('brinidx', 2)) limit 5; + pages + --------- + (6,137) + (6,138) + (6,139) + (6,140) + (6,141) + ``` + +- brin_page_items(page bytea, index oid) returns setof record + + 返回存储在BRIN数据页面中的数据。例如: + + ```sql + MogDB=# SELECT * FROM brin_page_items(get_raw_page('brinidx', 5), + 'brinidx') + ORDER BY blknum, attnum LIMIT 6; + itemoffset | blknum | attnum | allnulls | hasnulls | placeholder | value + ------------+--------+--------+----------+----------+-------------+-------------- + 137 | 0 | 1 | t | f | f | + 137 | 0 | 2 | f | f | f | {1 .. 88} + 138 | 4 | 1 | t | f | f | + 138 | 4 | 2 | f | f | f | {89 .. 176} + 139 | 8 | 1 | t | f | f | + 139 | 8 | 2 | f | f | f | {177 .. 264} + ``` + +## 使用示例 + +```sql +#创建一张测试表 +MogDB=# CREATE TABLE testtab (id int NOT NULL PRIMARY KEY,date TIMESTAMP NOT NULL, level INTEGER, msg TEXT); +NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index "testtab_pkey" for table "testtab" +CREATE TABLE +#插入测试数据 +MogDB=# INSERT INTO testtab (id, date, level, msg) SELECT g, CURRENT_TIMESTAMP + ( g || 'minute' ) :: interval, random() * 6, md5(g::text) FROM generate_series(1,8000000) as g; +INSERT 0 8000000 +#不创建索引的情况下查看一条查询语句的执行计划,可以看到执行计划用的是 seq scan +MogDB=# explain analyze select * from public.testtab where date between '2019-08-08 14:40:47.974791' and '2019-08-08 14:50:47.974791'; + QUERY PLAN +--------------------------------------------------------------------------------------------------------------------------------------------- + Seq Scan on testtab (cost=0.00..212024.20 rows=43183 width=48) (actual time=46620.314..46620.314 rows=0 loops=1) + Filter: (("date" >= '2019-08-08 14:40:47.974791'::timestamp without time zone) AND ("date" <= '2019-08-08 14:50:47.974791'::timestamp without time zone)) + Rows Removed by Filter: 8000000 + Total runtime: 46620.580 ms +(4 rows) +#在表上创建 brin 索引 +MogDB=# create index testtab_date_brin_idx on testtab using brin (date); +CREATE INDEX +#查看 brin 索引的索引信息,可以看到 brin 索引的大小大约为 64 kB +MogDB=# \di+ testtab_date_brin_idx  + List of relations + Schema | Name | Type | Owner | Table | Size | Storage | Description +--------+------------------------+-------+--------+---------+-------+---------+------------- + public | testtab_date_brin_idx  | index | wusong | testtab | 64 kB | | +(1 row) +#查看相同查询语句的执行计划,可以看到查询使用 brin 索引 +MogDB=# explain analyze select * from public.testtab where date between '2019-08-08 14:40:47.974791' and '2019-08-08 14:50:47.974791'; + QUERY PLAN +----------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Bitmap Heap Scan on testtab (cost=20.00..24.02 rows=1 width=49) (actual time=1.121..1.121 rows=0 loops=1) + Recheck Cond: (("date" >= '2019-08-08 14:40:47.974791'::timestamp without time zone) AND ("date" <= '2019-08-08 14:50:47.974791'::timestamp without time zone)) + -> Bitmap Index Scan on "testtab_date_brin_idx " (cost=0.00..20.00 rows=1 width=0) (actual time=1.119..1.119 rows=0 loops=1) + Index Cond: (("date" >= '2019-08-08 14:40:47.974791'::timestamp without time zone) AND ("date" <= '2019-08-08 14:50:47.974791'::timestamp without time zone)) + Total runtime: 1.281 ms +(5 rows) +#在表的 date 列上创建 btree 索引 +MogDB=# create index testtab_date_idx  on testtab(date); +CREATE INDEX +#查看 btree 索引的大小,可以看到 btree 索引大小约为 172 MB,远大于 brin 索引的 64 KB +MogDB=# \di+ testtab_date_idx  + List of relations + Schema | Name | Type | Owner | Table | Size | Storage | Description +--------+-------------------+-------+--------+---------+--------+---------+------------- + public | testtab_date_idx  | index | wusong | testtab | 172 MB | | +(1 row) + +``` + +## 相关页面 + +[CREATE INDEX](../../reference-guide/sql-syntax/CREATE-INDEX.md)、[DROP INDEX](../../reference-guide/sql-syntax/DROP-INDEX.md)、[ALTER INDEX](../../reference-guide/sql-syntax/ALTER-INDEX.md)、[VACUUM](../../reference-guide/sql-syntax/VACUUM.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/25-bloom-index.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/25-bloom-index.md new file mode 100644 index 00000000..6c8b1ad1 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/25-bloom-index.md @@ -0,0 +1,211 @@ +--- +title: BLOOM索引 +summary: BLOOM索引 +author: Guo Huan +date: 2022-06-21 +--- + +# BLOOM索引 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +Bloom提供了一种基于布鲁姆过滤器的索引访问方法。布鲁姆过滤器是一种空间高效的数据结构,它被用来测试一个元素是否为一个集合的成员。在索引访问方法的情况下,它可以通过尺寸在索引创建时决定的签名来快速地排除不匹配的元祖。 + +## 客户价值 + +Bloom索引适用于表中有很多列,并且查询可以使用任意列组合的场景。对于传统的索引,如Btree在这种场景下可能需要建很多个索引来覆盖可能的查询条件,可能导致索引占用空间很大,且影响插入和更新的性能,而Bloom索引只需要建一个就可以应对。 + +## 特性描述 + +用户在Bloom索引的适用场景下可以通过Bloom索引进行查询,同时相对于Btree索引还可以减少索引占用空间大小。 + +## 使用场景 + +当表具有很多属性并且查询可能会测试其中任意组合时,Blooms类型的索引最有用,传统的btree索引会比Bloom索引更快,但需要很多btree索引来支持所有可能的查询,而对于Bloom只需要一个即可。 + +### 创建Bloom索引 + +#### 约束 + +- Bloom 索引只支持在行存表上创建 + +- 创建索引的列类型只能是4字节长度的int类型或变长字符串类型,在MogDB中4字节长度的int类型可以是int、int4和integer,变长字符串类型可以是varchar、text和clob。 + +- Bloom不支持创建唯一索引 + +- 不支持索引null值,null值跳过 +- 只支持等值查询 +- 不支持分区表Global索引 + +#### 示例 + +```sql +CREATE INDEX ON USING bloom(col1,col2...) with (length=80,col1=2,col2=4); +``` + +#### 参数说明 + +**length** + +指定一条索引中生成的签名使用多少bit表示。默认值是80,内部会将用户指定的值会向上取整为16的整数倍(对用户透明),最小值是1,最大值是4096。如果设置值不在限定范围内,命令执行报错,并提示数值的正确范围。 + +**col1-col32** + +指定每一个索引列使用多少bit表示。默认值是2,最小值是1,最大值是4095。如果设置值不在限定范围内,命令执行报错,并提示数值的正确范围。 + +如果对非行存表创建Bloom索引,报错,提示不能对非行存表创建。 + +如果创建Bloom的唯一索引,报错,提示不能创建唯一索引。 + +如果创建分区表的Global索引,且索引类型是Bloom,报错,提示分区表Global索引只能是Btree类型。 + +### 删除Bloom索引 + +示例: + +```sql +MogDB=# DROP INDEX bloom_idx; +DROP INDEX +``` + +### 重建Bloom索引 + +本特性支持重建一个已存在的Bloom索引。用户通过客户端或者数据库驱动下发重建Bloom索引的命令,索引最终重建成功,索引元数据正确,索引可以正常使用(如,原来执行计划走 Bloom 索引的,在索引重建后,执行计划仍能使用重建后的 Bloom 索引)。 + +示例: + +```sql +MogDB=# REINDEX INDEX bloom_idx; +REINDEX +``` + +### 修改Bloom索引 + +本特性支持修改一个已存在的Bloom索引的属性。索引属性相关约束与创建索引时的约束保持一致,如Bloom索引的length修改后需要在[1,4096]的范围内。 + +关注点: + +- 修改的索引属性需要符合索引规则和约束,如果不符合需要报错,返回对应的提示信息; +- 重命名索引,在pg_class中校验索引元数据是否正确; +- 修改Bloom索引的length或col属性,如果要验证属性是否生效可以简单通过pg_class中relpages字段的值的变化判断,或者通过SELECT pg_size_pretty(pg_relation_size(‘blidx’))等命令查看索引大小的变化; +- 修改tablespace,可以通过在磁盘上查看数据文件的方式,确认是否生效。 + +示例: + +```sql +MogDB=# ALTER INDEX IF EXISTS bloom_idx RENAME TO newbloom_idx; +ALTER INDEX +MogDB=# SELECT oid,relname,relfilenode,relpages FROM pg_class WHERE relname = 'newbloom_idx'; + oid | relname | relfilenode | relpages +-------+--------------+-------------+---------- + 41159 | newbloom_idx | 41160 | 30 +(1 row) +MogDB=# ALTER INDEX IF EXISTS newbloom_idx SET (length=160); +ALTER INDEX +MogDB=# REINDEX INDEX newbloom_idx; +REINDEX +MogDB=# SELECT oid,relname,relfilenode,relpages FROM pg_class WHERE relname = 'newbloom_idx'; + oid | relname | relfilenode | relpages +-------+--------------+-------------+---------- + 41159 | newbloom_idx | 41162 | 49 +(1 row) +``` + +### 使用Bloom索引查询 + +当表上存在Bloom索引,且查询条件符合Bloom索引的适用条件时,执行计划会显示已使用Bloom索引。 + +示例: + +```sql +CREATE TABLE tbloom AS + SELECT + (random() * 1000000)::int as i1, + (random() * 1000000)::int as i2, + (random() * 1000000)::int as i3, + (random() * 1000000)::int as i4, + (random() * 1000000)::int as i5, + (random() * 1000000)::int as i6 + FROM + generate_series(1,10000000); + +CREATE INDEX btreeidx ON tbloom (i1, i2, i3, i4, i5, i6); +CREATE INDEX bloomidx ON tbloom USING bloom (i1, i2, i3, i4, i5, i6); + +MogDB=# EXPLAIN ANALYZE SELECT * FROM tbloom where i3 = 100 AND i5 = 1000; + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------------ + Bitmap Heap Scan on tbloom (cost=178436.31..179393.23 rows=250 width=24) (actual time=138.209..138.209 rows=0 loops=1) + Recheck Cond: ((i3 = 100) AND (i5 = 1000)) + Rows Removed by Index Recheck: 21936 + Heap Blocks: exact=18673 + -> Bitmap Index Scan on bloomidx (cost=0.00..178436.25 rows=250 width=0) (actual time=85.681..85.681 rows=21936 loops=1) + Index Cond: ((i3 = 100) AND (i5 = 1000)) + Total runtime: 138.412 ms +(7 rows) + +MogDB=# EXPLAIN ANALYZE SELECT * FROM tbloom where i1 = 100 AND i2 = 1000; + QUERY PLAN +----------------------------------------------------------------------------------------------------------------------- + [Bypass] + Index Only Scan using btreeidx on tbloom (cost=0.00..8.27 rows=1 width=24) (actual time=0.084..0.084 rows=0 loops=1) + Index Cond: ((i1 = 100) AND (i2 = 1000)) + Heap Fetches: 0 + Total runtime: 0.134 ms +(5 rows) +``` + +### 更新Bloom索引 + +示例: + +```sql +MogDB=# select i2,i3,i4 from tbloom where rownum <=5; + i2 | i3 | i4 +--------+--------+-------- + 778090 | 624067 | 948170 + 927435 | 800792 | 904419 + 325217 | 726778 | 834407 + 925272 | 221411 | 826500 + 93906 | 992575 | 997677 + +UPDATE tbloom SET i1 = 10 + WHERE i2 = 325217 AND + i3 = 726778 AND + i4 = 834407; + +MogDB=# select * from tbloom where i2 = 325217 and i3 = 726778; + i1 | i2 | i3 | i4 | i5 | i6 +----+--------+--------+--------+--------+-------- + 10 | 325217 | 726778 | 834407 | 702579 | 525581 +(1 row) + +MogDB=# explain select * from tbloom where i2 = 325217 and i3 = 726778; + QUERY PLAN +---------------------------------------------------------------------------- + Bitmap Heap Scan on tbloom (cost=178439.48..178443.50 rows=1 width=24) + Recheck Cond: ((i2 = 325217) AND (i3 = 726778)) + -> Bitmap Index Scan on bloomidx (cost=0.00..178439.48 rows=1 width=0) + Index Cond: ((i2 = 325217) AND (i3 = 726778)) +(4 rows) + +DELETE FROM tbloom WHERE i2 = 1000 AND i3 = 789678 AND i4 = 311551; +select * from tbloom where i2 = 1000 and i3 = 789678; + i1 | i2 | i3 | i4 | i5 | i6 +----+----+----+----+----+---- +(0 rows) +explain select * from tbloom where i2 = 1000 and i3 = 789678; + Bitmap Heap Scan on tbloom (cost=178440.26..178444.28 rows=1 width=24) + Recheck Cond: ((i2 = 1000) AND (i3 = 789678)) + -> Bitmap Index Scan on tbloomidx (cost=0.00..178440.26 rows=1 width=0) + Index Cond: ((i2 = 1000) AND (i3 = 789678)) +(4 rows) +``` + +## 相关页面 + +[CREATE INDEX](../../reference-guide/sql-syntax/CREATE-INDEX.md)、[DROP INDEX](../../reference-guide/sql-syntax/DROP-INDEX.md)、[ALTER INDEX](../../reference-guide/sql-syntax/ALTER-INDEX.md) \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/26-backend-compression.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/26-backend-compression.md new file mode 100644 index 00000000..5f0974ba --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/26-backend-compression.md @@ -0,0 +1,28 @@ +--- +title: 后台压缩 +summary: 后台压缩 +author: Guo Huan +date: 2022-06-22 +--- + +# 后台压缩 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +MogDB 3.0.0版本在Astore行存场景下支持数据压缩功能。前台业务线程执行DML语句对一个table中数据进行新增或修改,数据的操作只会在buffer缓存中执行,前台业务不参与实际压缩逻辑。 + +## 客户价值 + +减少客户存储成本,采用数据压缩的形式存储数据到持久化介质上,同时在开启压缩功能的情况下不会对前台业务造成性能影响,同时消除前台压缩长对性能的影响。 + +## 特性约束 + +如何支持压缩功能通过在创建表时指明压缩属性来实现,下面列出基本的SQL语法: + +```sql +create table (......) with (compression=yes); +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/3-full-text-indexing.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/3-full-text-indexing.md new file mode 100644 index 00000000..6eba688d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/3-full-text-indexing.md @@ -0,0 +1,53 @@ +--- +title: 全文索引 +summary: 全文索引 +author: Guo Huan +date: 2022-05-07 +--- + +# 全文索引 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +MogDB中提供的全文索引功能可以对文档进行预处理,并且可以使后续的搜索更快速。 + +## 客户价值 + +MogDB全文索引功能提供了查询可读性文档的能力,并且通过查询相关度将结果进行排序。 + +## 特性描述 + +构建全文索引的预处理过程包括: + +- 将文档解析成token。 + + 为每个文档标记不同类别的token是非常有必要的,例如:数字、文字、复合词、电子邮件地址,这样就可以做不同的处理。原则上token的类别依赖于具体的应用,但对于大多数的应用来说,可以使用一组预定义的token类。 + +- 将token转换为词素。 + + 词素像token一样是一个字符串,但它已经标准化处理,这样同一个词的不同形式是一样的。例如,标准化通常包括:将大写字母折成小写字母、删除后缀(如英语中的s或者es)。这将允许通过搜索找到同一个词的不同形式,不需要繁琐地输入所有可能的变形样式。同时,这一步通常会删除停用词。这些停用词通常因为太常见而对搜索无用。(总之,token是文档文本的原片段,而词素被认为是有用的索引和搜索词。)MogDB使用词典执行这一步,且提供了各种标准的词典。 + +- 保存搜索优化后的预处理文档。 + + 比如,每个文档可以呈现为标准化词素的有序组合。伴随词素,通常还需要存储词素位置信息以用于邻近排序。因此文档包含的查询词越密集其排序越高。词典能够对token如何标准化做到细粒度控制。使用合适的词典,可以定义不被索引的停用词。 + +## 特性增强 + +无。 + +## 特性约束 + +MogDB的全文检索功能当前限制约束是: + +- 每个分词长度必须小于2KB。 +- tsvector结构(分词+位置)的长度必须小于1MB。 +- tsvector的位置值必须大于0,且小于等于16,383。 +- 每个分词在文档中位置数必须小于256,若超过将舍弃后面的位置信息。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/4-copy-interface-for-error-tolerance.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/4-copy-interface-for-error-tolerance.md new file mode 100644 index 00000000..a731e54f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/4-copy-interface-for-error-tolerance.md @@ -0,0 +1,36 @@ +--- +title: Copy接口支持容错机制 +summary: Copy接口支持容错机制 +author: Guo Huan +date: 2022-05-07 +--- + +# Copy接口支持容错机制 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +支持将Copy过程中的部分错误导入到指定的错误表中,并且保持Copy过程不被中断。 + +## 客户价值 + +提升Copy功能的可用性和易用性,提升对于源数据格式异常等常见错误的容忍性和鲁棒性。 + +## 特性描述 + +MogDB提供用于创建函数的封装好的Copy错误表,并允许用户在使用Copy From指令时指定容错选项,使得Copy From语句在执行过程中部分解析、数据格式、字符集等相关的报错不会报错中断事务、而是被记录至错误表中,使得在Copy From的目标文件即使有少量数据错误也可以完成入库操作。用户随后可以在错误表中对相关的错误进行定位以及进一步排查。 + +## 特性增强 + +无。 + +## 特性约束 + +支持容错的具体错误种类请参见《管理指南》中“使用COPY FROM STDIN导入数据 > [处理错误表](../../administrator-guide/importing-and-exporting-data/importing-data/3-running-the-COPY-FROM-STDIN-statement-to-import-data.md#处理错误表)”章节。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/5-partitioning.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/5-partitioning.md new file mode 100644 index 00000000..72df1db2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/5-partitioning.md @@ -0,0 +1,58 @@ +--- +title: 分区 +summary: 分区 +author: Guo Huan +date: 2022-05-07 +--- + +# 分区 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +数据分区是在一个节点内部对数据按照用户指定的策略做进一步的水平分表,将表按照指定范围划分为多个数据互不重叠的部分。 + +## 客户价值 + +对于大多数用户使用场景,分区表和普通表相比具有以下优点: + +- 改善查询性能:对分区对象的查询可以仅搜索自己关心的分区,提高检索效率。 +- 增强可用性:如果分区表的某个分区出现故障,表在其他分区的数据仍然可用。 +- 均衡I/O:可以把不同的分区映射到不同的磁盘以平衡I/O,改善整个系统性能。 + +## 特性描述 + +目前MogDB数据库支持范围分区表、列表分区表、哈希分区表: + +- 范围分区表:将数据基于范围映射到每一个分区,这个范围是由创建分区表时指定的分区键决定的。这种分区方式是最为常用的。 + + 范围分区功能,即根据表的一列或者多列,将要插入表的记录分为若干个范围(这些范围在不同的分区里没有重叠),然后为每个范围创建一个分区,用来存储相应的数据。 + +- 列表分区表:将数据基于各个分区内包含的键值映射到每一个分区,分区包含的键值在创建分区时指定。 + + 列表分区功能,即根据表的一列,将要插入表的记录中出现的键值分为若干个列表(这些列表在不同的分区里没有重叠),然后为每个列表创建一个分区,用来存储相应的数据。 + +- 哈希分区表:将数据通过哈希映射到每一个分区,每一个分区中存储了具有相同哈希值的记录。 + + 哈希分区功能,即根据表的一列,通过内部哈希算法将要插入表的记录划分到对应的分区中。 + +用户在CREATE TABLE时增加PARTITION参数,即表示针对此表应用数据分区功能。用户可以在实际使用中根据需要调整建表时的分区键,使每次查询结果尽可能存储在相同或者最少的分区内(称为“分区剪枝”),通过获取连续I/O大幅度提升查询性能。 + +实际业务中,时间经常被作为查询对象的过滤条件。因此,用户可考虑选择时间列为分区键,键值范围可根据总数据量、一次查询数据量调整。 + +## 特性增强 + +支持范围分区表的合并功能。 + +List/Hash分区表支持数据交换。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/6-support-for-advanced-analysis-functions.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/6-support-for-advanced-analysis-functions.md new file mode 100644 index 00000000..bd9fee24 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/6-support-for-advanced-analysis-functions.md @@ -0,0 +1,57 @@ +--- +title: 高级分析函数支持 +summary: 高级分析函数支持 +author: Guo Huan +date: 2022-05-07 +--- + +# 高级分析函数支持 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +无。 + +## 客户价值 + +我们提供窗口函数来进行数据高级分析处理。窗口函数将一个表中的数据进行预先分组,每一行属于一个特定的组,然后在这个组上进行一系列的关联分析计算。这样可以挖掘出每一个元组在这个集合里的一些属性和与其他元组的关联信息。 + +## 特性描述 + +简单举例说明窗口分析功能:分析某一部门内每个人的薪水和部门平均薪水的对比。 + +```sql +SELECT depname, empno, salary, avg(salary) OVER (PARTITION BY depname) FROM empsalary; +depname | empno | salary | avg +-----------+-------+--------+----------------------- +develop | 11 | 5200 | 5020.0000000000000000 +develop | 7 | 4200 | 5020.0000000000000000 +develop | 9 | 4500 | 5020.0000000000000000 +develop | 8 | 6000 | 5020.0000000000000000 +develop | 10 | 5200 | 5020.0000000000000000 +personnel | 5 | 3500 | 3700.0000000000000000 +personnel | 2 | 3900 | 3700.0000000000000000 +sales | 3 | 4800 | 4866.6666666666666667 +sales | 1 | 5000 | 4866.6666666666666667 +sales | 4 | 4800 | 4866.6666666666666667 +(10 rows) +``` + +可以看到,通过这个avg(salary) OVER (PARTITION BY depname)分析函数,每一个人的薪水和与部门的平均薪水很容易计算出来。 + +目前,系统支持row_number(),rank(),dense_rank(),percent_rank(),cume_dist(),ntile(),lag(),lead(),first_value(),last_value(),nth_value()分析函数。具体的函数用法和语句请参见《参考指南》中“系统函数 > [窗口函数](../../reference-guide/functions-and-operators/18-window-functions.md)”章节。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/7-materialized-view.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/7-materialized-view.md new file mode 100644 index 00000000..801971aa --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/7-materialized-view.md @@ -0,0 +1,36 @@ +--- +title: 物化视图 +summary: 物化视图 +author: Guo Huan +date: 2022-05-07 +--- + +# 物化视图 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +物化视图实际上就是一种特殊的物理表,物化视图是相对普通视图而言的。普通视图是虚拟表,应用的局限性较大,任何对视图的查询实际上都是转换为对SQL语句的查询,性能并没有实际上提高。而物化视图实际上就是存储SQL所执行语句的结果,起到缓存的效果。 + +## 客户价值 + +使用物化视图功能提升查询效率。 + +## 特性描述 + +支持全量物化视图和增量物化视图,全量物化视图只支持全量更新。增量物化视图可实现异步更新功能,用户可通过执行语句把新增数据刷新到物化视图中。 + +## 特性增强 + +无。 + +## 特性约束 + +仅支持基表简单过滤查询和UNION ALL语句。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/8-hyperloglog.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/8-hyperloglog.md new file mode 100644 index 00000000..97f446b9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/8-hyperloglog.md @@ -0,0 +1,38 @@ +--- +title: 支持HyperLogLog +summary: 支持HyperLogLog +author: Guo Huan +date: 2022-05-07 +--- + +# 支持HyperLogLog + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +通过使用HyperLogLog相关函数,计算唯一值个数Count(Distinct),提升性能。 + +## 客户价值 + +提升AP/TP类查询的性能。 + +## 特性描述 + +HLL(HyperLogLog)是统计数据集中唯一值个数的高效近似算法。它有着计算速度快,节省空间的特点,不需要直接存储集合本身,而是存储一种名为HLL的数据结构。每当有新数据加入进行统计时,只需要把数据经过哈希计算并插入到HLL中,最后根据HLL就可以得到结果。 + +HLL在计算速度和所占存储空间上都占优势。在时间复杂度上,Sort算法需要排序至少O(nlogn)的时间,虽说Hash算法和HLL一样扫描一次全表O(n)的时间就可以得出结果,但是存储空间上,Sort算法和Hash算法都需要先把原始数据存起来再进行统计,会导致存储空间消耗巨大。而对HLL来说不需要存原始数据,只需要维护HLL数据结构,所以占用空间始终是1280字节常数级别。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/9-creating-an-index-online.md b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/9-creating-an-index-online.md new file mode 100644 index 00000000..4f2cc7a2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/enterprise-level-features/9-creating-an-index-online.md @@ -0,0 +1,40 @@ +--- +title: 在线添加索引 +summary: 在线添加索引 +author: Guo Huan +date: 2022-05-07 +--- + +# 在线添加索引 + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +通过create index concurrently语法,以不阻塞DML的方式在线创建索引。 + +## 客户价值 + +创建索引时指定concurrently关键字,可以实现创建过程中不阻塞DML,不阻塞用户在线业务。 + +## 特性描述 + +创建索引时,一般会阻塞其他语句对该索引所依赖表的访问。指定concurrently关键字,对表加的是ShareUpdateExclusiveLock锁,可以实现创建过程中不阻塞DML。 + +在线添加索引,需要执行先后两次对该表的权标扫描来完成build,第一次扫描的时候创建索引,不阻塞读写操作;第二次扫描的时候合并更新第一次扫描到目前为止发生的变更。由于需要执行两次对表的扫描和build,而且必须等待现有的所有可能对该表执行修改的事务结束。这意味着该索引的创建比正常耗时更长,同时因此带来的CPU和I/O消耗对其他业务也会造成影响。 + +## 特性增强 + +无。 + +## 特性约束 + +- 在线添加索引时只能指定一个索引的名称。 +- 普通CREATE INDEX命令可以在事务内执行,但是CREATE INDEX CONCURRENTLY不可以在事务内执行。 +- 列存表、分区表和临时表不支持CONCURRENTLY方式创建索引。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/1-primary-standby.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/1-primary-standby.md new file mode 100644 index 00000000..ef30f9e8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/1-primary-standby.md @@ -0,0 +1,42 @@ +--- +title: 主备机 +summary: 主备机 +author: Guo Huan +date: 2022-05-07 +--- + +# 主备机 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始支持DN主备。 + +## 特性简介 + +为了保证故障的可恢复,需要将数据写多份,设置主备多个副本,通过日志进行数据同步,可以实现节点故障、停止后重启等情况下,MogDB能够保证故障之前的数据无丢失,满足ACID特性。 + +## 客户价值 + +主备机功能可以支持主机故障时切换到备机,数据不丢失,业务可以快速恢复。 + +## 特性描述 + +主备环境可以支持主备从和一主多备两种模式。主备从模式下,备机需要重做日志,可以升主,而从备只能接收日志,不可以升主。而在一主多备模式下,所有的备机都需要重做日志,都可以升主。主备从主要用于大数据分析类型的OLAP系统,能够节省一定的存储资源。而一主多备提供更高的容灾能力,更加适合于大批量事务处理的OLTP系统。 + +当主备机均正常可用时,主备之间可以通过switchover进行角色切换;当主机故障后,可以通过failover对备机进行升主。 + +初始化安装或者备份恢复等场景中,需要根据主机重建备机的数据,此时需要build功能,将主机的数据和WAL日志发送到备机。主机故障后重新以备机的角色加入时,也需要build功能将其数据和日志与新主拉齐。另外,在在线扩容的场景中,需要通过build来同步元数据到新节点上的实例。build包含全量build和增量build,全量build要全部依赖主机数据进行重建,拷贝的数据量比较大,耗时比较长,而增量build只拷贝差异文件,拷贝的数据量比较小,耗时比较短。一般情况下,优先选择增量build来进行故障恢复,如果增量build失败,再继续执行全量build,直至故障恢复。 + +为了实现所有实例的高可用容灾能力,除了以上对DN设置主备多个副本,MogDB还提供了其他一些主备容灾能力,使得实例故障后可以尽快地恢复,不中断业务,将因为硬件、软件和人为造成的故障对业务的影响降到最低,以保证业务的连续性。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/10-adding-or-deleting-a-standby-server.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/10-adding-or-deleting-a-standby-server.md new file mode 100644 index 00000000..405e0faa --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/10-adding-or-deleting-a-standby-server.md @@ -0,0 +1,59 @@ +--- +title: 备机增加删除 +summary: 备机增加删除 +author: Guo Huan +date: 2022-05-07 +--- + +# 备机增加删除 + +## 可获得性 + +本特性自MogDB 2.0.0 版本开始引入。 + +## 特性简介 + +支持新增和删除备节点。 + +## 客户价值 + +- 当主数据库的读取压力较大,或者用户想要提升数据库灾难恢复能力,需要新增备节点。 +- 当集群中的某些备节点发生故障无法短时间内进行修复时,为保证集群状态正常,用户可以先将故障节点删除。 + +## 特性描述 + +- 支持从单机或者一主多备状态下最多扩容至一主八备,支持新增级联备机,支持在集群中存在故障备机的情况下新增备节点。 +- 支持从一主多备删除至单节点,支持备机故障的情况下将其删除。 +- 支持在线新增和删除备节点,即可以在不影响主机业务的情况下进行新增和删除备节点。 + +## 特性增强 + +无。 + +## 特性约束 + +新增备机的约束: + +- 数据库主机上存在MogDB镜像包。 +- 在新增的扩容备机上创建好与主机上相同的用户和用户组。 +- 已存在的数据库节点和新增的扩容节点之间需要建立好root用户互信以及数据库管理用户的互信。 +- 正确配置xml文件,在已安装数据库配置文件的基础上,添加需要扩容的备机信息。 +- 只能使用root用户执行扩容命令。 +- 不允许同时在主节点上执行gs_dropnode命令删除其他备机。 +- 执行扩容命令前需要导入主机数据库的环境变量。 +- 扩容备机的操作系统与主机保持一致。 +- 操作过程中不允许同时在其他备节点上执行主备倒换或者故障倒换的操作。 + +删除备机的约束: + +- 删除备节点的操作只能在主节点上执行。 +- 操作过程中不允许同时在其他备节点上执行主备倒换或者故障倒换的操作。 +- 不允许同时在主节点上执行gs_expansion命令进行扩容。 +- 不允许同时执行2次相同的gs_dropnode命令。 +- 执行删除操作前,需要确保主节点和备节点之间建立好数据库管理用户的互信。 +- 需要使用数据库管理用户执行该命令。 +- 执行命令前需要通过source命令导入主机数据库的环境变量。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/11-delaying-entering-the-maximum-availability-mode.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/11-delaying-entering-the-maximum-availability-mode.md new file mode 100644 index 00000000..5fdfc297 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/11-delaying-entering-the-maximum-availability-mode.md @@ -0,0 +1,42 @@ +--- +title: 延迟进入最大可用模式 +summary: 延迟进入最大可用模式 +author: Guo Huan +date: 2022-05-10 +--- + +# 延迟进入最大可用模式 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +支持主机延迟进入最大可用模式。 + +## 客户价值 + +当主机与同步备机之间的网络不稳定或其他原因导致主机感知到备机退出,且主机打开最大可用模式配置时,在一定时间窗内仍维持主机在最大保护模式的状态,超出该时间窗口后,主机进入到最大可用模式。 + +可以避免因网络抖动、进程闪断等因素导致主机在最大保护模式和最大可用模式之间频繁来回切换。 + +## 特性描述 + +当最大可用模式most_available_sync配置为on,在主备场景下,当存在同步备发生故障,导致不满足当前所配置的同步备数量(详细可参考synchronous_standby_names的含义)时,如果配置了keep_sync_window参数,则在keep_sync_window设置的时间窗口内,继续保持最大保护模式,即阻塞主机的事务提交,延缓进入最大可用模式的时间。 + +若在keep_sync_window超时窗口内,同步备机故障恢复,且满足当前所配置的同步备数量,则不阻塞事务,恢复到正常状态。 + +## 特性增强 + +无。 + +## 特性约束 + +- 该特性仅在最大可用模式打开的前提下生效。 +- 启用该特性可能会对RPO造成影响, 若主机在所配置的超时时间窗口内发生故障,主机的事务只在本地提交,未同步到故障的同步备机。 +- 该特性不适用于级联备机。 + +## 依赖关系 + +依赖最大可用模式。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/12-parallel-logical-decoding.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/12-parallel-logical-decoding.md new file mode 100644 index 00000000..da255e90 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/12-parallel-logical-decoding.md @@ -0,0 +1,53 @@ +--- +title: 并行逻辑解码 +summary: 并行逻辑解码 +author: Guo Huan +date: 2022-05-10 +--- + +# 并行逻辑解码 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +支持多线程并行解码。 + +## 客户价值 + +大幅提升逻辑解码性能,解码速度由3~5MBps可提升到标准场景(16核CPU、内存128G、网络带宽 > 200MBps、表的列数为10\~100、单行数据量0.1KB\~1KB、DML操作以insert为主、不涉及落盘事务即单个事务中语句数量小于4096)下的100MBps。 + +## 特性描述 + +在使用JDBC或pg_recvlogical解码时,设置配置选项parallel-decode-num为大于1且小于等于20的值,开启并行解码特性,使用一个读取线程、多个解码线程以及一个发送线程协同进行逻辑解码操作,显著提升解码速度。 + +## 特性增强 + +无。 + +## 特性约束 + +1. 当前的硬件和网络环境正常;由于逻辑日志一般为xlog的两倍,为保证xlog速度达到100MBps,I/O带宽至少保证200MBps;因为reader、decoder、sender线程均需预留资源,CPU需预留并发数+2的核数,如4并发场景需要预留6核。在实际场景中,使用备机解码即可保证需求,无需进行特殊的资源预留规划。为保证解码性能达标以及尽量降低对业务的影响,一台备机上应尽量仅建立一个并行解码连接,保证CPU、内存、带宽资源充足。 +2. 日志级别的guc参数wal_level = logical。 +3. guc参数max_replication_slots >= 每个DN所需的(物理流复制槽数+备份槽数+逻辑复制槽数)。 +4. 解码配置选项parallel-decode-num > 1且<= 20,指定并行的解码线程数。 +5. 不支持DDL语句解码。 +6. 不支持列存、数据页复制的解码。 +7. 不支持解码分布式事务,当前机制为从DN解码,无法保证分布式事务一致性解码。 +8. 单条元组大小不超过1GB,考虑解码结果可能大于插入数据,因此建议单条元组大小不超过500MB。 +9. 不支持压缩表的DML语句解码。 +10. MogDB支持解码的数据类型为:INTEGER、BIGINT、SMALLILNT、TINYINT、SERIAL、SMALLSERIAL、BIGSERIAL、FLOAT、DOUBLE PRECISION、DATE、TIME[WITHOUT TIME ZONE]、TIMESTAMP[WITHOUT TIME ZONE]、CHAR(n)、VARCHAR(n)、TEXT。 +11. 在需要ssl连接的场景,需要前置条件保证guc参数ssl = on。 +12. 不支持interval partition表复制。 +13. 在事务中执行DDL语句后,该DDL语句与之后的语句不会被解码。 +14. 如需进行备机解码,需在对应主机上设置guc参数enable_slot_log = on。 +15. 当前不支持超大CLOB解码。 +16. 不允许主备,多个备机同时使用同一个复制槽解码,否则会产生数据不一致。 +17. 禁止在使用逻辑复制槽时在其他节点对该复制槽进行操作,删除复制槽的操作需在该复制槽停止解码后执行。 +18. 仅支持内置'j'风格导出,不支持wal2json插件。 + +## 依赖关系 + +依赖备机解码。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/13-dcf.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/13-dcf.md new file mode 100644 index 00000000..07496f61 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/13-dcf.md @@ -0,0 +1,45 @@ +--- +title: DCF +summary: DCF +author: Guo Huan +date: 2022-05-10 +--- + +# DCF + +## 可获得性 + +本特性自MogDB 2.0.0版本开始引入。 + +## 特性简介 + +DCF(Distributed Consensus Framework,分布式共识框架)基于Paxos算法实现数据同步强一致。DCF模式开关开启后,DN可以支持基于Paxos协议的复制与仲裁能力。 + +## 客户价值 + +DN基于Paxos的自选主及日志复制,复制过程中支持压缩及流控,防止带宽占用过高。使用DCF可以提供日志复制、集群高可用等能力。DCF提供了自选主能力,支持少数派强起能力,日志复制支持动态流量调整。同时也提供了基于Paxos多种角色节点类型,并能进行调整。支持查询当前数据库实例的状态。 + +DCF是一款高性能、高度成熟可靠、易扩展、易使用的独立基础库,其他系统通过接口与DCF简单对接,就能够轻松拥有Paxos算法赋予的强一致、高可用、自动容灾等能力。 + +## 特性描述 + +- DCF进行日志复制时,支持对日志进行压缩后再传输,减小对网络带宽的占用。 +- DCF支持SSL,包括TLS1.2和TLS1.3协议标准。当开启SSL时,DN默认将DCF配置为TLS1.2协议标准。 +- DCF支持5种TLS1.3的密码套件:TLS13-AES-256-GCM-SHA384、TLS13-CHACHA20-POLY1305-SHA256、TLS13-AES-128-GCM-SHA256、TLS13-AES-128-CCM-8-SHA256、TLS13-AES-128-CCM-SHA256。 +- DCF支持passive角色节点类型,passive节点不参与选举,只做日志的同步以及回放,该类型节点在高负载的情况下,日志同步会做流控。 +- DCF支持logger角色节点,logger节点可以参与选举和投票,但是只复制DCF的日志,不复制xlog,不进行redo。 +- DCF的follower和passive角色可以在线互换,即不中断业务的情况下,follower角色的节点转化为passive角色,passive角色的节点转化为follower。 +- DCF支持少数派强起能力,在数据库实例多数派故障的情况下,从正常的备DN中选择少数派模式强启成为主DN,其余正常的备DN从主DN复制日志。 +- DCF支持自选主能力,在原主DN故障的场景下,在保证数据一致性的前提下,剩余备DN自动选出新的主DN。 + +## 特性增强 + +无。 + +## 特性约束 + +若使用此功能,在安装部署阶段需要开启DCF开关。在DCF模式下通过多数派选举,安装过程中如果故障节点数加build节点数达到多数派会导致集群安装失败,如在安装一主两备时,安装过程中一节点因内存不足导致安装失败,另外两节点正常启动,但随后备机会进行一次build,这时build节点加故障节点为2,达到多数派会导致集群安装失败,请在安装过程中检查内存和磁盘等资源是否充足。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/14-cm.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/14-cm.md new file mode 100644 index 00000000..a72921e3 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/14-cm.md @@ -0,0 +1,62 @@ +--- +title: CM +summary: CM +author: Guo Huan +date: 2022-05-10 +--- + +# CM + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +CM(Cluster Manager)是一款数据库管理软件,可分为四大模块:cm_server, cm_agent, om_monitor, cm_ctl。其核心功能如下: + +- cm_server + + 向各个节点上cm_agent发送指令(如数据库实例的启动、停止、状态查询、switchover和failover),并接收响应; + + 接收各个节点上cm_agent上报的数据库实例状态信息; + + 各个节点上cm_server自身高可用仲裁; + + 各个节点上数据库实例的高可用仲裁。 + +- cm_agent + + 接收并执行cm_server下发的指令,如数据库实例的启动、停止、状态查询、switchover和failover; + + 监控本节点上运行的数据库实例的状态并上报给cm_server。 + +- cm_monitor + + 监控本节点上运行的cm_agent服务,确保其可用性。 + +- cm_ctl + + CM集群管理软件的客户端工具。 + +## 客户价值 + +管理和监控数据库系统中各个功能单元和物理资源的运行情况,确保整个系统的可用性、稳定性。 + +## 特性描述 + +支持自定义资源监控,提供了数据库主备的状态监控、网络通信故障监控、文件系统故障监控、故障自动主备切换等能力。提供了丰富的数据库管理能力,如节点、实例级的启停,数据库实例状态查询、主备切换、日志管理等。 + +## 特性增强 + +- CM高可用自仲裁,内嵌仲裁算法和逻辑,不依赖于第三方组件即可实现仲裁; + +- 自定义资源监控。 + +## 特性约束 + +一主一备模式下,CM只支持基本的安装、启停、检测能力,其他功能不支持。 + +## 依赖关系 + +高可用仲裁依赖DCF、DCC、CBB组件。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/15-global-syscache.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/15-global-syscache.md new file mode 100644 index 00000000..71f10c5a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/15-global-syscache.md @@ -0,0 +1,43 @@ +--- +title: 支持global syscache +summary: 支持global syscache +author: Guo Huan +date: 2022-05-10 +--- + +# 支持global syscache + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +全局系统缓存(Global SysCache)是系统表数据的全局缓存和本地缓存。原理如图1所示。 + +**图 1** Global SysCache原理图 + + ![Global-SysCache原理图](https://cdn-mogdb.enmotech.com/docs-media/mogdb/characteristic-description/Global-SysCache.png) + +## 客户价值 + +全局系统缓存特性可以降低数据库进程的缓存内存占用,提升数据库的并发扩展能力。 + +## 特性描述 + +全局系统缓存特性指将系统缓存与会话解耦,绑定到线程上,结合线程池特性达到降低内存占用的目的,同时结合全局缓存,提升缓存命中率,保持性能稳定。 + +## 特性增强 + +支持更高的并发查询。 + +## 特性约束 + +- 设置enable_global_syscache为on。建议设置enable_thread_pool参数为on。 +- 当DB数较多,且阈值global_syscache_threshold较小时,内存控制无法正常工作,性能会劣化。 +- 不支持分布式时序相关的任务,这些任务的内存控制与性能不受GSC特性的影响。 +- wal_level设置为minimal或者archive时,备机的查询性能会下降,会退化为短连接。 + +## 依赖关系 + +该特性降内存能力依赖于线程池特性。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/16-using-a-standby-node-to-build-a-standby-node.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/16-using-a-standby-node-to-build-a-standby-node.md new file mode 100644 index 00000000..92bd885c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/16-using-a-standby-node-to-build-a-standby-node.md @@ -0,0 +1,36 @@ +--- +title: 支持备机build备机 +summary: 支持备机build备机 +author: Guo Huan +date: 2022-05-10 +--- + +# 支持备机build备机 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +备机build备机加快备机故障的恢复。 减小主机io和带宽压力。 + +## 客户价值 + +当业务压力过大时,从主机build备机会对主机的资源造成影响,导致主机性能下降、build变慢的情况。使用备机build备机不会对主机业务造成影响。 + +## 特性描述 + +使用gs_ctl命令可以指定对应的备机去build需要修复的备机。具体操作可参考《参考指南》中的“[gs_ctl](../../reference-guide/tool-reference/tools-used-in-the-internal-system/4-gs_ctl.md)”章节。 + +## 特性增强 + +无。 + +## 特性约束 + +只支持备机build备机,只能使用指定ip和port的方式做build,同时在build前应确保需要修复备机的日志比发送数据的备机的日志落后。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/2-logical-replication.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/2-logical-replication.md new file mode 100644 index 00000000..75c89dc6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/2-logical-replication.md @@ -0,0 +1,37 @@ +--- +title: 逻辑复制 +summary: 逻辑复制 +author: Guo Huan +date: 2022-05-07 +--- + +# 逻辑复制 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +MogDB提供逻辑解码功能,将物理日志反解析为逻辑日志。通过DRS等逻辑复制工具将逻辑日志转化为SQL语句,到对端数据库回放,达到异构数据库同步数据的功能。目前支持MogDB数据库与MySQL数据库、Oracle数据库之间的单向、双向逻辑复制。 + +## 客户价值 + +逻辑复制可以为数据库数据实时迁移、双库双活、支持滚动升级提供解决方案。 + +## 特性描述 + +DN通过物理日志反解析为逻辑日志,DRS等逻辑复制工具从DN抽取逻辑日志转换为SQL语句,到对端数据库(MySQL)回放。逻辑复制工具同时从MySQL数据库抽取逻辑日志,反解析为SQL语句之后回放到MogDB,达到异构数据库同步数据的目的。 + +## 特性增强 + +- MogDB 1.1.0逻辑解码新增全量+增量抽取日志的方案。 +- MogDB 1.1.0逻辑解码新增备机支持逻辑解码。 + +## 特性约束 + +不支持列存复制,不支持DDL复制。 + +## 依赖关系 + +依赖于逻辑复制工具对逻辑日志进行解码。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/3-online-node-replacement.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/3-online-node-replacement.md new file mode 100644 index 00000000..dedf21b5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/3-online-node-replacement.md @@ -0,0 +1,36 @@ +--- +title: 在线节点替换 +summary: 在线节点替换 +author: Guo Huan +date: 2022-05-07 +--- + +# 在线节点替换 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +数据库内某节点出现硬件故障造成节点不可用或者实例状态不正常,当数据库没有加锁,通过节点替换或修复故障实例来恢复数据库的过程中,支持用户DML操作,有限场景支持用户DDL操作。 + +## 客户价值 + +随着企业数据规模不断增大,节点数量急剧增加,硬件损坏概率相应增加,物理节点替换修复成为日常运维工作的常态。传统的离线节点替换方式无法满足客户业务不中断需求,日常运维操作中,经常的业务中断将给客户带来重大损失。而目前业界数据库产品在节点替换的过程中,或者需要中断业务,或者只允许部分操作,均不能满足大规模数据情况下,常态物理节点替换的需求。 + +## 特性描述 + +数据库内某节点出现硬件故障造成节点不可用或者实例状态不正常,通过节点替换或修复故障实例来恢复数据库的过程中,支持用户DML操作,有限场景支持用户DDL操作。 + +## 特性增强 + +无。 + +## 特性约束 + +目前节点替换已支持用户业务在线DDL:在节点替换窗口期内,支持用户DML操作,有限场景支持用户DDL操作。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/4-logical-backup.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/4-logical-backup.md new file mode 100644 index 00000000..2155a2f5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/4-logical-backup.md @@ -0,0 +1,40 @@ +--- +title: 逻辑备份 +summary: 逻辑备份 +author: Guo Huan +date: 2022-05-07 +--- + +# 逻辑备份 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +支持将数据库内用户表的数据以通用格式备份到指定的存储介质中。 + +## 客户价值 + +通过逻辑备份特性,可以达成以下目的: + +- 将用户数据备份到可靠性更高的存储介质中,提升用户表数据的可靠性。 +- 通过采用通用的数据格式,支持跨版本恢复和异构恢复。 +- 可以用于冷数据的归档。 + +## 特性描述 + +MogDB提供逻辑备份能力,可以将用户表的数据以通用的text或者csv格式备份到本地磁盘文件中,并在同构/异构数据库中恢复该用户表的数据。 + +## 特性增强 + +无。 + +## 特性约束 + +逻辑备份的约束条件请参见《参考指南》中“[gs_dump](../../reference-guide/tool-reference/server-tools/5-gs_dump.md)”章节。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/5-physical-backup.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/5-physical-backup.md new file mode 100644 index 00000000..f0579bc0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/5-physical-backup.md @@ -0,0 +1,52 @@ +--- +title: 物理备份 +summary: 物理备份 +author: Guo Huan +date: 2022-05-07 +--- + +# 物理备份 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +支持将整个数据库的数据以内部格式备份到指定的存储介质中。 + +## 客户价值 + +通过物理备份特性,可以达成以下目的: + +- 整个数据库的数据备份到可靠性更高的存储介质中,提升系统整体的可靠性。 +- 通过采用数据库内部的数据格式,极大提升备份恢复性能。 +- 可以用于冷数据的归档。 + +典型的物理备份策略和应用场景如下: + +- 周一,执行数据库全量备份 +- 周二,以周一全量备份为基准点,执行增量备份 +- 周三,以周二增量备份为基准点,执行增量备份 +- … +- 周日,以周六增量备份为基准点,执行增量备份 + +上述备份策略以一个星期为周期。 + +## 特性描述 + +MogDB 1.1.0 提供物理备份能力,可以将整个数据库的数据以数据库内部格式备份到本地磁盘文件、OBS对象、NBU对象或爱数对象中,并在同构数据库中恢复整个数据库的数据。在基础之上,还提供压缩、流控、断点续备等高阶功能。 + +物理备份主要分为全量备份和增量备份,区别如下:全量备份包含备份时刻点上数据库的全量数据,耗时时间长(和数据库数据总量成正比),自身即可恢复出完整的数据库;增量备份只包含从指定时刻点之后的增量修改数据,耗时时间短(和增量数据成正比,和数据总量无关),但是必须要和全量备份数据一起才能恢复出完整的数据库。 + +## 特性增强 + +支持全量备份和增量备份同时执行。 + +## 特性约束 + +物理备份的约束条件请参见《管理指南》中“备份与恢复 > [物理备份恢复](../../administrator-guide/br/1-2-br.md)”章节相关约束。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/6-automatic-job-retry-upon-failure.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/6-automatic-job-retry-upon-failure.md new file mode 100644 index 00000000..b0617a46 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/6-automatic-job-retry-upon-failure.md @@ -0,0 +1,93 @@ +--- +title: 作业失败自动重试 +summary: 作业失败自动重试 +author: Guo Huan +date: 2022-05-07 +--- + +# 作业失败自动重试 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +批处理作业中,在由于网络异常、锁冲突等出错情况下能够保证作业自动重试。 + +## 客户价值 + +网络异常、锁冲突等出错场景下无需人工干预,自动对出错查询进行重试,提高了可用性。 + +## 特性描述 + +MogDB数据库提供作业重试机制gsql Retry。 + +gsql Retry,对于需要进行重试的错误使用唯一的错误码(SQL STATE)进行标识。对客户端工具gsql进行功能增强,使用错误码配置文件(retry_errcodes.conf,置于和gsql同级的安装目录下)对需要重试的错误列表进行配置。gsql提供如下元命令来开启/关闭错误重试功能,重试次数设为范围为5~10,缺省值为5。 + +``` +set RETRY [number] +``` + +打开该功能时gsql会读取上述配置文件,错误重试控制器通过容器记录错误码列表。如果打开后出现配置文件中某一个错误,控制器会将每次缓存的查询语句重新发送给服务端进行重试,直到成功或超过重试次数报错。 + +## 特性增强 + +无。 + +## 特性约束 + +- 功能范围限制: + + 仅能提高故障发生时SQL语句执行成功率,不能保证100%的执行成功。 + +- 错误类型约束: + + SQL语句出错时能够被识别和重试的错误,仅限在表1中定义的错误。 + + **表 1** 支持的错误类型列表 + + | 错误类型 | 错误码 | 备注 | + | :----------------------------------------------------------- | :----- | :----------------------------------------------------------- | + | 对端连接重置(CONNECTION_RESET_BY_PEER) | YY001 | TCP通信错误:Connection reset by peer | + | 对端流重置(STREAM_CONNECTION_RESET_BY_PEER) | YY002 | TCP通信错误:Stream connection reset by peer(DN和DN间通信) | + | 锁等待超时(LOCK_WAIT_TIMEOUT) | YY003 | 锁超时,Lock wait timeout | + | 连接超时(CONNECTION_TIMED_OUT) | YY004 | TCP通信错误,Connection timed out | + | 查询设置错误(SET_QUERY_ERROR) | YY005 | SET命令发送失败,Set query error | + | 超出逻辑内存(OUT_OF_LOGICAL_MEMORY) | YY006 | 内存申请失败,Out of logical memory | + | 通信库内存分配(SCTP_MEMORY_ALLOC) | YY007 | SCTP通信错误,Memory allocate error | + | 无通信库缓存数据(SCTP_NO_DATA_IN_BUFFER) | YY008 | SCTP通信错误,SCTP no data in buffer | + | 通信库释放内存关闭(SCTP_RELEASE_MEMORY_CLOSE) | YY009 | SCTP通信错误,Release memory close | + | SCTP、TCP断开(SCTP_TCP_DISCONNECT) | YY010 | SCTP、TCP通信错误,SCTP、TCP disconnect | + | 通信库断开(SCTP_DISCONNECT) | YY011 | SCTP通信错误,SCTP disconnect | + | 通信库远程关闭(SCTP_REMOTE_CLOSE) | YY012 | SCTP通信错误,Stream closed by remote | + | 等待未知通信库通信(SCTP_WAIT_POLL_UNKNOW) | YY013 | 等待未知通信库通信,SCTP wait poll unknow | + | 无效快照(SNAPSHOT_INVALID) | YY014 | 快照非法,Snapshot invalid | + | 通讯接收信息错误(ERRCODE_CONNECTION_RECEIVE_WRONG) | YY015 | 连接获取错误,Connection receive wrong | + | 内存耗尽(OUT_OF_MEMORY) | 53200 | 内存耗尽,Out of memory | + | 连接异常(CONNECTION_EXCEPTION) | 08000 | 连接出现错误,和DN的通讯失败,Connection exception | + | 管理员关闭系统(ADMIN_SHUTDOWN) | 57P01 | 管理员关闭系统,Admin shutdown | + | 关闭远程流接口(STREAM_REMOTE_CLOSE_SOCKET) | XX003 | 关闭远程套接字,Stream remote close socket | + | 重复查询编号(ERRCODE_STREAM_DUPLICATE_QUERY_ID) | XX009 | 重复查询,Duplicate query id | + | stream查询并发更新同一行(ERRCODE_STREAM_CONCURRENT_UPDATE) | YY016 | stream查询并发更新同一行,Stream concurrent update | + +- 语句类型约束: + + 支持单语句存储过程、函数、匿名块。不支持事务块中的语句。 + +- 存储过程语句约束: + + - 包含EXCEPTION的存储过程,如果在执行过程中(包含语句块执行和EXCEPTION中的语句执行)错误被抛出,可以retry,如果报错被EXCEPTION捕获则不能retry。 + - 不支持使用全局变量的高级包。 + - 不支持DBE_TASK。 + - 不支持PKG_UTIL文件操作。 + +- 数据导入约束: + + - 不支持COPY FROM STDIN语句。 + - 不支持gsql \copy from元命令。 + - 不支持JDBC CopyManager copyIn导入数据。 + +## 依赖关系 + +该特性依赖gsql工具端可以正常工作、错误列表配置正确。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/7-ultimate-rto.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/7-ultimate-rto.md new file mode 100644 index 00000000..1fe377f1 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/7-ultimate-rto.md @@ -0,0 +1,39 @@ +--- +title: 极致RTO +summary: 极致RTO +author: Guo Huan +date: 2022-05-07 +--- + +# 极致RTO + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +- 支撑数据库主机重启后快速恢复的场景。 +- 支撑主机与同步备机通过日志同步,加速备机回放的场景。 + +## 客户价值 + +当业务压力过大时,备机的回放速度跟不上主机的速度。在系统长时间的运行后,备机上会出现日志累积。当主机故障后,数据恢复需要很长时间,数据库不可用,严重影响系统可用性。 + +开启极致RTO(Recovery Time Object,恢复时间目标),减少了主机故障后数据的恢复时间,提高了可用性。 + +## 特性描述 + +极致RTO开关开启后,xlog日志回放建立多级流水线,提高并发度,提升日志回放速度。 + +## 特性增强 + +无。 + +## 特性约束 + +极致RTO只关注同步备机的RTO是否满足需求。极致RTO本身有流控效果,无需打开流控功能开关。本特性不支持备机读。如果查询备机可能导致备机宕机。本特性不支持主备从场景。如果配置成支持主备从(配置了replication_type=0),数据库无法拉起。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/8-cascaded-standby-server.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/8-cascaded-standby-server.md new file mode 100644 index 00000000..d060e7ee --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/8-cascaded-standby-server.md @@ -0,0 +1,45 @@ +--- +title: 级联备机 +summary: 级联备机 +author: Guo Huan +date: 2022-05-07 +--- + +# 级联备机 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +本特性主要基于当前一主多备的架构,在此基础上,支持级联备机连接备机。 + +## 客户价值 + +一主多备架构在特性业务场景下,无法支持足够灵活的结构。多机房部署,不足以满足HA切换下的完整结构(主次机房三个实例,再次机房两到三个实例)。若备机个数变多,对主机可能导致压力较大。针对业务实时性要求较低的查询,可落到级联备中。因此,我们需要提供级联备能力。 + +## 特性描述 + +主机通过发送日志给备机实现同步,备机通过发送日志给级联备实现同步,其中主备之间日志同步可配置为同步或异步,备机与级联备之间只能以异步方式。 + +目前一主多备方式架构,主机通过walsender线程向备机同步日志,备机通过walreceiver线程接受日志,并刷到本地盘,备机读取redo日志,完成主备之间的数据同步。主备机之间walsender与walreceiver一一对应。备机与级联备通过walsender与walreceiver线程异步方式同步日志,降低主机流复制的压力。 + +## 特性增强 + +无。 + +## 特性约束 + +- 级联备只能从备机同步数据,不能直接从主机同步。 +- 级联备不支持直接从备机build数据,目前只能从主机build数据。如果备机需要全量build,会导致级联备也要重新全量build。 +- 级联备为异步同步。 +- 级联备不支持promote。 +- 级联备不支持notify。 +- 目前不提供查询主 - 备 - 级联备集群总体架构,需要根据主找到备,再通过备找到级联备。 +- 级联备不能有再次级联备。 +- 极致RTO开启时,不支持级联备。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/9-delayed-replay.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/9-delayed-replay.md new file mode 100644 index 00000000..e5e4f7d6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-availability/9-delayed-replay.md @@ -0,0 +1,46 @@ +--- +title: 延时回放 +summary: 延时回放 +author: Guo Huan +date: 2022-05-07 +--- + +# 延时回放 + +## 可获得性 + +本特性自MogDB 2.0.0 版本开始引入。 + +## 特性简介 + +支持备机延时回放。 + +## 客户价值 + +默认情况下,备机会尽快恢复来自于主机的XLOG记录。这个功能允许备机将回放延时一段指定的时间后进行回放。提供一份可查询一段时间之前的数据副本,可以更方便的纠正用户误操作等错误。 + +## 特性描述 + +支持通过配置GUC参数recovery_min_apply_delay设定延时时间,使某个备机延时一段时间回放来自主机的事务日志。 + +参数取值范围:整型,0~INT_MAX,单位为毫秒。 + +参数默认值:0(不增加延迟) + +## 特性增强 + +无。 + +## 特性约束 + +- recovery_min_apply_delay参数主节点设置无效,必须设置在需要延迟的备节点上。 +- 延迟时间是根据主服务器上事务提交的时间戳与备机上的当前时间来计算,因此需要保证主备系统时钟一致。 +- 没有事务的操作不会被延迟。 +- 主备切换之后,原主机若需延迟,需要再手动配置此参数。 +- 当synchronous_commit被设置为remote_apply时,同步复制会受到这个延时的影响,每一个COMMIT都需要等待备机回放结束后才会返回。 +- 使用这个特性也会让hot_standby_feedback被延迟,这可能导致主服务器的膨胀,两者一起使用时要小心。 +- 主机执行了持有AccessExclusive锁的DDL操作,比如DROP和TRUNCATE操作,在备机延迟回放该条记录期间,在备机上对该操作对象执行查询操作会等待锁释放之后才会返回。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/1-cbo-optimizer.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/1-cbo-optimizer.md new file mode 100644 index 00000000..a907ed92 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/1-cbo-optimizer.md @@ -0,0 +1,36 @@ +--- +title: CBO优化器 +summary: CBO优化器 +author: Guo Huan +date: 2022-05-07 +--- + +# CBO优化器 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +MogDB优化器是基于代价的优化(Cost-Based Optimization,简称CBO)。 + +## 客户价值 + +MogDB CBO优化器能够在众多计划中依据代价选出最高效的执行计划,最大限度的满足客户业务要求。 + +## 特性描述 + +在CBO优化器模型下,数据库根据表的元组数、字段宽度、NULL记录比率、DISTINCT值、MCV值、HB值等表的特征值,以及一定的代价计算模型,计算出每一个执行步骤的不同执行方式的输出元组数和执行代价(cost),进而选出整体执行代价最小、首元组返回代价最小的执行方式进行执行。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/10-xlog-no-lock-flush.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/10-xlog-no-lock-flush.md new file mode 100644 index 00000000..6b6e6715 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/10-xlog-no-lock-flush.md @@ -0,0 +1,36 @@ +--- +title: Xlog no Lock Flush +summary: Xlog no Lock Flush +author: Guo Huan +date: 2022-05-07 +--- + +# Xlog no Lock Flush + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +取消WalInsertLock争抢及WalWriter专用磁盘写入线程。 + +## 客户价值 + +在保持原有XLog功能不变的基础上,进一步提升系统性能。 + +## 特性描述 + +对WalInsertLock进行优化,利用LSN(Log Sequence Number)及LRC(Log Record Count)记录了每个backend的拷贝进度,取消WalInsertLock机制。在backend将日志拷贝至WalBuffer时,不用对WalInsertLock进行争抢,可直接进行日志拷贝操作。并利用专用的WalWriter写日志线程,不需要backend线程自身来保证xlog的Flush。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/11-parallel-page-based-redo-for-ustore.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/11-parallel-page-based-redo-for-ustore.md new file mode 100644 index 00000000..3b072284 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/11-parallel-page-based-redo-for-ustore.md @@ -0,0 +1,36 @@ +--- +title: Parallel Page-based Redo For Ustore +summary: Parallel Page-based Redo For Ustore +author: Guo Huan +date: 2022-05-07 +--- + +# Parallel Page-based Redo For Ustore + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +优化Ustore Inplace Update WAL log写入,Ustore DML Operation回放提高并行度。 + +## 客户价值 + +对于Update的WAL使用空间减少,Ustore DML Operation回放提高并行度。 + +## 特性描述 + +通过利用Prefix和suffix来减少update WAL log的写入,通过把回放线程分多个类型来解决Ustore DML WAL大多都是多页面回放问题;同时把Ustore的数据页面回放按照blkno去分发。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +依赖于Ustore引擎。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/12-row-store-execution-to-vectorized-execution.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/12-row-store-execution-to-vectorized-execution.md new file mode 100644 index 00000000..9787c2af --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/12-row-store-execution-to-vectorized-execution.md @@ -0,0 +1,40 @@ +--- +title: 行存转向量化 +summary: 行存转向量化 +author: Guo Huan +date: 2022-05-10 +--- + +# 行存转向量化 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +将行存表的查询转换为向量化执行计划执行,提升复杂查询的执行性能。 + +## 客户价值 + +由于行存执行引擎在执行包含较多表达式或者关联操作的复杂查询时,性能表现不佳;而向量化执行引擎在执行复杂查询时具有优异的性能表现。所以通过将行存表的查询转换为向量化执行计划执行,能够有效提升复杂查询的查询性能。 + +## 特性描述 + +本特性通过对扫描算子增加一层RowToVec的操作,将行存表的数据在内存中变为向量化格式后,上层算子都能够转化为对应的向量化算子,从而使用向量化执行引擎计算。支持行转列的扫描算子包括:SeqScan、IndexOnlyscan、IndexScan、BitmapScan、FunctionScan、ValueScan、TidScan。 + +## 特性增强 + +无。 + +## 特性约束 + +- 不支持向量化的场景包括: + - targetList存在返回set的函数。 + - targetList或者qual中存在不支持向量化的表达式:数组类表达式计算;多子查询表达式计算;Field类表达式计算;系统表列。 + - 包含不支持向量化的类型:POINTOID;LSEGOID;BOXOID;LINEOID;CIRCLEOID;POLYGONOID;PATHOID;用户自定义类型。 +- MOT表不支持转向量化。 + +## 依赖关系 + +向量化引擎 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/2-llvm.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/2-llvm.md new file mode 100644 index 00000000..ea8c1a3d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/2-llvm.md @@ -0,0 +1,36 @@ +--- +title: 支持LLVM +summary: 支持LLVM +author: Guo Huan +date: 2022-05-07 +--- + +# 支持LLVM + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +MogDB的LLVM(Low Level Virtual Machine)技术,提供了查询动态编译执行的能力。 + +## 客户价值 + +通过对查询动态编译执行,大幅提高重查询性能。 + +## 特性描述 + +MogDB借助LLVM提供的库函数,依据查询执行计划树,将原本在执行器阶段才会确定查询实际执行路径的过程提前到执行初始化阶段,从而规避原本查询执行时候伴随的函数调用、逻辑条件分支判断以及大量的数据读取等问题,以达到提升查询性能的目的。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +依赖于LLVM开源组件,当前使用的开源组件版本为10.0.0。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/3-vectorized-engine.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/3-vectorized-engine.md new file mode 100644 index 00000000..e97589e5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/3-vectorized-engine.md @@ -0,0 +1,43 @@ +--- +title: 向量化引擎 +summary: 向量化引擎 +author: Guo Huan +date: 2022-05-07 +--- + +# 向量化引擎 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +MogDB提供向量化引擎,通常用在OLAP数据仓库类系统。主要是因为分析型系统通常是数据处理密集型,基本上都是采用顺序方式来访问表中大部分的数据,然后再进行计算,最后将计算结果输出给用户。 + +## 客户价值 + +通过批量计算,大幅提高复杂类查询性能。 + +## 特性描述 + +传统的数据库查询执行都是采用一次一数组(tuple)的pipeline执行模式,因此CPU的大部分处理时间不是用来处理数据,而是遍历查询操作树。这种情况下CPU的有效利用率不高,同时也会导致低指令缓存性能和频繁跳转。更加糟糕的是,这种方式的执行,不能够利用现代硬件的新优化特征来加速查询的执行。在执行引擎中,另外一个解决方案就是改变一次一数组(tuple)为一次一列的模式。这也是我们向量化执行引擎的一个基础。 + +向量化引擎是跟列存储技术绑定的,因为列存储时每列数据存储在一起,可以认为这些数据是以数组的方式存储的。基于这样的特征,当该列数据需要进行某一同样操作,可以通过一个循环来高效完成对这个数据块各个值的计算。 + +向量化执行引擎的优势在于: + +- 可以减少节点间的调度,提高CPU的利用率。 +- 因为相同类型的数据放在一起,可以更容易的利用硬件与编译的新优化特征。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +依赖于列存储。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/4-hybrid-row-column-store.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/4-hybrid-row-column-store.md new file mode 100644 index 00000000..24e8e9f7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/4-hybrid-row-column-store.md @@ -0,0 +1,72 @@ +--- +title: 行列混合存储 +summary: 行列混合存储 +author: Guo Huan +date: 2022-05-07 +--- + +# 行列混合存储 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +MogDB支持行存储和列存储两种存储模型,用户可以根据具体的使用场景,建表时选择行存储还是列存储表。 + +一般情况下,如果表的字段比较多(即大宽表),查询中涉及到列不很多的情况下,适合列存储。列存储方式如图1所示。如果表的字段个数比较少,查询大部分字段,那么选择行存储比较好。 + +**图 1** 列存储示意图 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/characteristic-description/hybrid-row-column-store.png) + +## 客户价值 + +在大宽表、数据量比较大的场景中,查询经常关注某些列,行存储引擎查询性能比较差。例如,气象局的场景,单表有200~800个列,查询经常访问10个列,在类似这样的场景下,向量化执行技术和列存储引擎可以极大的提升性能和减少存储空间。 + +## 特性描述 + +表有行存表和列存表两种存储模型。两种存储模型各有优劣,建议根据实际情况选择。 + +- 行存表 + + 默认创建表的类型。数据按行进行存储,即一行数据紧挨着存储。行存表支持完整的增删改查。适用于对数据需要经常更新的场景。 + +- 列存表 + +数据按列进行存储,即一列所有数据紧挨着存储。单列查询IO小,比行存表占用更少的存储空间。适合数据批量插入、更新较少和以查询为主统计分析类的场景。列存表不适合点查询,insert插入单条记录性能差。 + +行存表和列存表的选择依据如下: + +- 更新频繁程度 + + 数据如果频繁更新,选择行存表。 + +- 插入频繁程度 + + 频繁的少量插入,选择行存表。一次插入大批量数据,选择列存表。 + +- 表的列数 + + 表的列数很多,选择列存表。 + +- 查询的列数 + + 如果每次查询时,只涉及了表的少数(小于总列数的50%)几个列,选择列存表。 + +- 压缩率 + + 列存表比行存表压缩率高。但高压缩率会消耗更多的CPU资源。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/5-adaptive-compression.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/5-adaptive-compression.md new file mode 100644 index 00000000..3192a17a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/5-adaptive-compression.md @@ -0,0 +1,42 @@ +--- +title: 自适应压缩 +summary: 自适应压缩 +author: Guo Huan +date: 2022-05-07 +--- + +# 自适应压缩 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +数据压缩是当前数据库采用的主要技术。数据类型不同,适用于它的压缩算法不同。对于相同类型的数据,其数据特征不同,采用不同的压缩算法达到的效果也不相同。自适应压缩正是从数据类型和数据特征出发,采用相应的压缩算法,实现了良好的压缩比、快速的入库性能以及良好的查询性能。 + +## 客户价值 + +主要应用场景为数据入库和频繁的海量数据查询。 在数据入库场景中,自适应压缩可以大幅度地减少数据量,成倍提高IO操作效率,并将数据分类压缩以获得更快的入库性能。当用户进行数据查询时,少量的IO操作和快速的数据解压可以加快数据获取的速率,从而在更短的时间内得到查询结果。 + +## 特性描述 + +目前,数据库已实现了列存储上RLE、DELTA、BYTEPACK/BITPACK、LZ4、ZLIB、LOCAL DICTIONARY等多种压缩算法。数据库支持的数据类型与压缩算法的映射关系如下表所示。 + +| - | RLE | DELTA | BITPACK/BYTEPACK | LZ4 | ZLIB | LOCAL DICTIONARY | +| :----------------------------------------------------------- | :--- | :---- | :--------------- | :--- | :--- | :--------------- | +| smallint/int/bigint/oid
decimal/real/double
money/time/date/timestamp | √ | √ | √ | √ | √ | - | +| tinterval/interval/time with time zone/ | - | - | - | - | √ | - | +| numeric/char/varchar/text/nvarchar2
以及其他支持数据类型 | √ | √ | √ | √ | √ | √ | + +## 特性增强 + +支持对压缩算法进行不同压缩水平的调整。 + +## 特性约束 + +无。 + +## 依赖关系 + +开源压缩软件LZ4/ZLIB。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/6-sql-by-pass.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/6-sql-by-pass.md new file mode 100644 index 00000000..f9245d91 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/6-sql-by-pass.md @@ -0,0 +1,36 @@ +--- +title: SQL by pass +summary: SQL by pass +author: Guo Huan +date: 2022-05-07 +--- + +# SQL by pass + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +通过对OLTP场景典型查询的定制化执行方案来提高查询性能。 + +## 客户价值 + +提升OLTP类查询的性能。 + +## 特性描述 + +在典型的OLTP场景中,简单查询占了很大一部分比例。这种查询的特征是只涉及单表和简单表达式的查询,因此为了加速这类查询,提出了SQL by pass框架,在parse层对这类查询做简单的模式判别后,进入到特殊的执行路径里,跳过经典的执行器执行框架,包括算子的初始化与执行、表达式与投影等经典框架,直接重写一套简洁的执行路径,并且直接调用存储接口,这样可以大大加速简单查询的执行速度。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/7-kunpeng-numa-architecture-optimization.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/7-kunpeng-numa-architecture-optimization.md new file mode 100644 index 00000000..7e4cdbe6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/7-kunpeng-numa-architecture-optimization.md @@ -0,0 +1,40 @@ +--- +title: 鲲鹏NUMA架构优化 +summary: 鲲鹏NUMA架构优化 +author: Guo Huan +date: 2022-05-07 +--- + +# 鲲鹏NUMA架构优化 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +鲲鹏NUMA架构优化,主要面向鲲鹏处理器架构特点、ARMv8指令集等,进行相应的系统优化,涉及到操作系统、软件架构、锁并发、日志、原子操作、Cache访问等一系列的多层次优化,从而大幅提升了MogDB数据库在鲲鹏平台上的处理性能。 + +## 客户价值 + +数据库的处理性能,例如每分钟处理交易量(Transaction Per Minute),是数据库竞争力的关键性能指标,在同等硬件成本的条件下,数据库能提供的处理性能越高,就可以提供给用户更多的业务处理能力,从而降低客户的使用成本。 + +## 特性描述 + +- MogDB根据鲲鹏处理机的多核NUMA架构特点,进行一系列针对性NUMA架构相关优化。一方面尽量减少跨核内存访问的时延问题,另一方面充分发挥鲲鹏多核算力优势,所提供的关键技术包括重做日志批插、热点数据NUMA分布、CLog分区等,大幅提升TP系统的处理性能。 +- MogDB基于鲲鹏芯片所使用的ARMv8.1架构,利用LSE扩展指令集实现高效的原子操作,有效提升CPU利用率,从而提升多线程间同步性能、XLog写入性能等。 +- MogDB基于鲲鹏芯片提供的更宽的L3缓存cacheline,针对热点数据访问进行优化,有效提高缓存访问命中率,降低Cache缓存一致性维护开销,大幅提升系统整体的数据访问性能。 +- 鲲鹏920,2P服务器(64cores*2,内存768 GB),网络10 GE,IO为4块NVME PCIE SSD时,TPCC为1000warehouse,性能是150万tpmC。 + +## 特性增强 + +- 支持重做日志批插,分区CLog,提升鲲鹏平台下的数据库处理性能。 +- 支持LSE扩展指令集的原子操作,提升多线程同步性能。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/8-high-concurrency-of-thread-pools.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/8-high-concurrency-of-thread-pools.md new file mode 100644 index 00000000..15da27c0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/8-high-concurrency-of-thread-pools.md @@ -0,0 +1,37 @@ +--- +title: 支持线程池高并发 +summary: 支持线程池高并发 +author: Guo Huan +date: 2022-05-07 +--- + +# 支持线程池高并发 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +通过线程池化技术来支撑数据库大并发稳定运行。 + +## 客户价值 + +支撑客户大并发下,系统整体吞吐平稳。 + +## 特性描述 + +线程池技术的整体设计思想是线程资源池化、并且在不同连接之间复用。系统在启动之后会根据当前核数或者用户配置启动固定一批数量的工作线程,一个工作线程会服务一到多个连接会话,这样把会话和线程进行了解耦。因为工作线程数是固定的,因此在高并发下不会导致线程的频繁切换,而由数据库层来进行线程的调度管理。 + +## 特性增强 + +- MogDB 1.1.0版本引入该特性。 +- MogDB 1.1.0版本实现了线程池的动态扩缩容。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/9-smp-for-parallel-execution.md b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/9-smp-for-parallel-execution.md new file mode 100644 index 00000000..9e01627c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/high-performance/9-smp-for-parallel-execution.md @@ -0,0 +1,44 @@ +--- +title: SMP并行执行 +summary: SMP并行执行 +author: Guo Huan +date: 2022-05-07 +--- + +# SMP并行执行 + +## 可获得性 + +本特性自MogDB 1.1.0版本开始引入。 + +## 特性简介 + +MogDB的SMP并行技术是一种利用计算机多核CPU架构来实现多线程并行计算,以充分利用CPU资源来提高查询性能的技术。 + +## 客户价值 + +SMP并行技术充分利用了系统多核的能力,来提高重查询的性能。 + +## 特性描述 + +在复杂查询场景中,单个查询的执行较长,系统并发度低,通过SMP并行执行技术实现算子级的并行,能够有效减少查询执行时间,提升查询性能及资源利用率。SMP并行技术的整体实现思想是对于能够并行的查询算子,将数据分片,启动若干个工作线程分别计算,最后将结果汇总,返回前端。SMP并行执行增加数据交互算子**Stream**,实现多个工作线程之间的数据交互,确保查询的正确性,完成整体的查询。 + +## 特性增强 + +无。 + +## 特性约束 + +- 索引扫描不支持并行执行。 +- MergeJoin不支持并行执行。 +- WindowAgg order by不支持并行执行。 +- cursor不支持并行执行。 +- 存储过程和函数内的查询不支持并行执行。 +- 不支持子查询subplan和initplan的并行,以及包含子查询的算子的并行。 +- 查询语句中带有median操作的查询不支持并行执行。 +- 带全局临时表的查询不支持并行执行。 +- 物化视图的更新不支持并行执行。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/1-gray-upgrade.md b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/1-gray-upgrade.md new file mode 100644 index 00000000..3d1a3019 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/1-gray-upgrade.md @@ -0,0 +1,36 @@ +--- +title: 灰度升级 +summary: 灰度升级 +author: Guo Huan +date: 2022-05-07 +--- + +# 灰度升级 + +## 可获得性 + +本特性自MogDB 2.0.0版本开始引入。 + +## 特性简介 + +灰度升级支持全业务操作,一次性升级所有节点。 + +## 客户价值 + +灰度升级提供了一种在线升级的方式,保证在不中断业务的情况下,对所有的节点进行升级。 + +## 特性描述 + +灰度升级是一种支持所有节点升级的在线升级方式。目前灰度升级只涉及数据库二进制的替换,为了尽可能降低对于业务的影响,采用同一节点两套二进制同时存在的方式,使用软连接切换的方式来进行进程版本的切换升级(闪断一次,10秒以内)。 + +## 特性增强 + +无。 + +## 特性约束 + +灰度升级的约束条件请参见《管理指南》中的[升级指南](../../administrator-guide/upgrade-guide.md)章节。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/2-workload-diagnosis-report.md b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/2-workload-diagnosis-report.md new file mode 100644 index 00000000..a34cb4ca --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/2-workload-diagnosis-report.md @@ -0,0 +1,72 @@ +--- +title: 支持WDR诊断报告 +summary: 支持WDR诊断报告 +author: Guo Huan +date: 2022-05-07 +--- + +# 支持WDR诊断报告 + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +WDR报告提供数据库性能诊断报告,该报告基于基线性能数据和增量数据两个版本,从性能变化得到性能报告。 + +## 客户价值 + +- WDR报表是长期性能问题最主要的诊断手段。基于SNAPSHOT的性能基线,从多维度做性能分析,能帮助DBA掌握系统负载繁忙程度、各个组件的性能表现及性能瓶颈。 +- SNAPSHOT也是后续性能问题自诊断和自优化建议的重要数据来源。 + +## 特性描述 + +WDR(Workload Diagnosis Report)基于两次不同时间点系统的性能快照数据,生成这两个时间点之间的性能表现报表,用于诊断数据库内核的性能故障。 + +使用generate_wdr_report(…) 可以生成基于两个性能快照的性能报告。 + +WDR主要依赖两个组件: + +- SNAPSHOT性能快照:性能快照可以配置成按一定时间间隔从内核采集一定量的性能数据,持久化在用户表空间。任何一个SNAPSHOT可以作为一个性能基线,其他SNAPSHOT与之比较的结果,可以分析出与基线的性能表现。 +- WDR Reporter:报表生成工具基于两个SNAPSHOT,分析系统总体性能表现,并能计算出更多项具体的性能指标在这两个时间段之间的变化量,生成SUMMARY 和DETAIL两个不同级别的性能数据。如表1、表2所示。 + +**表 1** SUMMARY级别诊断报告 + +| 诊断类别 | 描述 | +| :------------------------------ | :----------------------------------------------------------- | +| Database Stat | 主要用于评估当前数据库上的负载和IO状况,负载和IO状况是衡量TP系统最重要的特性。包含当前连接到该数据库的session,提交、回滚的事务数,读取的磁盘块的数量,高速缓存中已经发现的磁盘块的次数,通过数据库查询返回、抓取、插入、更新、删除的行数,冲突、死锁发生的次数,临时文件的使用量,IO读写时间等。 | +| Load Profile | 从时间,IO,事务,SQL几个维度评估当前系统负载的表现。包含作业运行elapse time、CPU time,事务日质量,逻辑和物理读的量,读写IO次数、大小,登入登出次数,SQL、事务执行量,SQL P80、P95响应时间等。 | +| Instance Efficiency Percentages | 用于评估当前系统的缓存的效率。主要包含数据库缓存命中率。 | +| Events | 用于评估当前系统内核关键资源,关键事件的性能。主要包含数据库内核关键事件的发生次数,事件的等待时间。 | +| Wait Classes | 用于评估当前系统关键事件类型的性能。主要包含数据内核在主要的等待事件的种类上的发布:STATUS、LWLOCK_EVENT、LOCK_EVENT、IO_EVENT。 | +| CPU | 主要包含CPU在用户态、内核态、Wait IO、空闲状态下的时间发布。 | +| IO Profile | 主要包含数据库Database IO次数、Database IO数据量、Redo IO次数、Redo IO量。 | +| Memory Statistics | 包含最大进程内存、进程已经使用内存、最大共享内存、已经使用共享内存大小等。 | + +**表 2** DETAIL级别诊断报告 + +| 诊断类别 | 描述 | +| :--------------------- | :----------------------------------------------------------- | +| Time Model | 主要用于评估当前系统在时间维度的性能表现。包含系统在各个阶段上消耗的时间:内核时间、CPU时间、执行时间、解析时间、编译时间、查询重写时间、计划生成时间、网络时间、IO时间。 | +| SQL Statistics | 主要用于SQL语句性能问题的诊断。包含归一化的SQL的性能指标在多个维度上的排序:Elapsed Time、CPU Time、Rows Returned、Tuples Reads、Executions、Physical Reads、Logical Reads。这些指标的种类包括:执行时间,执行次数、行活动、Cache IO等。 | +| Wait Events | 主要用于系统关键资源,关键时间的详细性能诊断。包含所有关键事件在一段时间内的表现,主要是事件发生的次数,消耗的时间。 | +| Cache IO Stats | 用于诊断用户表和索引的性能。包含所有用户表、索引上的文件读写,缓存命中。 | +| Utility status | 用于诊断后端作业性能的诊断。包含页面操作,复制等后端操作的性能。 | +| Object stats | 用于诊断数据库对象的性能。包含用户表、索引上的表、索引扫描活动,insert、update、delete活动,有效行数量,表维护操作的状态等。 | +| Configuration settings | 用于判断配置是否有变更。包含当前所有配置参数的快照。 | +| SQL detail | 显示unique query text信息。 | + +## 特性增强 + +无。 + +## 特性约束 + +- WDR snapshot性能快照会采集不同database的性能数据,如果数据库实例中有大量的database或者大量表,做一次WDR snapshot会花费很长时间。 +- 如果在大量DDL期间做WDR snapshot可能造成WDR snapshot失败。 +- 在drop database时,做WDR snapshot可能造成WDR snapshot失败。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/3-slow-sql-diagnosis.md b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/3-slow-sql-diagnosis.md new file mode 100644 index 00000000..79090692 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/3-slow-sql-diagnosis.md @@ -0,0 +1,137 @@ +--- +title: 慢SQL诊断 +summary: 慢SQL诊断 +author: Guo Huan +date: 2022-05-07 +--- + +# 慢SQL诊断 + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +重构前慢SQL相关视图已废弃,包括dbe_perf. gs_slow_query_info、dbe_perf.gs_slow_query_history、dbe_perf.global_slow_query_hisotry、dbe_perf.global_slow_query_info。 + +## 特性简介 + +慢SQL诊断提供诊断慢SQL所需要的必要信息,帮助开发者回溯执行时间超过阈值的SQL,诊断SQL性能瓶颈。 + +## 客户价值 + +慢SQL诊断提供给用户对于慢SQL所需的详细信息,用户无需通过复现就能离线诊断特定慢SQL的性能问题。表和函数接口方便用户统计慢SQL指标,对接第三方平台。 + +## 特性描述 + +慢SQL能根据用户提供的执行时间阈值(log_min_duration_statement),记录所有超过阈值的执行完毕的作业信息。 + +慢SQL提供表和函数两种维度的查询接口。用户从接口中能查询到作业的执行计划,开始、结束执行时间,执行查询的语句,行活动,内核时间,CPU时间,执行时间,解析时间,编译时间,查询重写时间,计划生成时间,网络时间,IO时间,网络开销,锁开销等。以上所有信息都是脱敏的。 + +## 特性增强 + +增加对慢SQL指标信息,安全性(脱敏),执行计划,查询接口的增强。 + +``` +执行命令查看数据库实例中SQL语句执行信息 +gsql> select * from dbe_perf.get_global_full_sql_by_timestamp(start_timestamp, end_timestamp); +例如: +MogDB=# select * from DBE_PERF.get_global_full_sql_by_timestamp('2020-12-01 09:25:22', '2020-12-31 23:54:41'); +-[ RECORD 1 ]--------+--------------------------------------------------------------------------------------------------------------- +--------------------------------------------------------------- +node_name | dn_6001_6002_6003 +db_name | postgres +schema_name | "$user",public +origin_node | 1938253334 +user_name | user_dj +application_name | gsql +client_addr | +client_port | -1 +unique_query_id | 3671179229 +debug_query_id | 72339069014839210 +query | select name, setting from pg_settings where name in (?) +start_time | 2020-12-19 16:19:51.216818+08 +finish_time | 2020-12-19 16:19:51.224513+08 +slow_sql_threshold | 1800000000 +transaction_id | 0 +thread_id | 139884662093568 +session_id | 139884662093568 +n_soft_parse | 0 +n_hard_parse | 1 +query_plan | Datanode Name: dn_6001_6002_6003 + | Function Scan on pg_show_all_settings a (cost=0.00..12.50 rows=5 width=64) + | Filter: (name = '***'::text) +... + +执行命令查看数据库实例中慢SQL语句执行信息 +gsql> select * from dbe_perf.get_global_slow_sql_by_timestamp(start_timestamp, end_timestamp); +MogDB=# select * from DBE_PERF.get_global_slow_sql_by_timestamp('2020-12-01 09:25:22', '2020-12-31 23:54:41'); +-[ RECORD 1 ]--------+--------------------------------------------------------------------------------------------------- +node_name | dn_6001_6002_6003 +db_name | postgres +schema_name | "$user",public +origin_node | 1938253334 +user_name | user_dj +application_name | gsql +client_addr | +client_port | -1 +unique_query_id | 2165004317 +debug_query_id | 72339069014839319 +query | select * from DBE_PERF.get_global_slow_sql_by_timestamp(?, ?); +start_time | 2020-12-19 16:23:20.738491+08 +finish_time | 2020-12-19 16:23:20.773714+08 +slow_sql_threshold | 10000 +transaction_id | 0 +thread_id | 139884662093568 +session_id | 139884662093568 +n_soft_parse | 10 +n_hard_parse | 8 +query_plan | Datanode Name: dn_6001_6002_6003 + | Result (cost=1.01..1.02 rows=1 width=0) + | InitPlan 1 (returns $0) + | -> Seq Scan on pgxc_node (cost=0.00..1.01 rows=1 width=64) + | Filter: (nodeis_active AND ((node_type = '***'::"char") OR (node_type = '***'::"char"))) +... + +查看当前节点SQL语句执行信息 +gsql> select * from statement_history; +例如: +MogDB=# select * from statement_history; +-[ RECORD 1 ]--------+--------------------------------------------------------------------------------------------------------------- +--------------------------------------------------------------- +db_name | postgres +schema_name | "$user",public +origin_node | 1938253334 +user_name | user_dj +application_name | gsql +client_addr | +client_port | -1 +unique_query_id | 3671179229 +debug_query_id | 72339069014839210 +query | select name, setting from pg_settings where name in (?) +start_time | 2020-12-19 16:19:51.216818+08 +finish_time | 2020-12-19 16:19:51.224513+08 +slow_sql_threshold | 1800000000 +transaction_id | 0 +thread_id | 139884662093568 +session_id | 139884662093568 +n_soft_parse | 0 +n_hard_parse | 1 +query_plan | Datanode Name: dn_6001_6002_6003 + | Function Scan on pg_show_all_settings a (cost=0.00..12.50 rows=5 width=64) + | Filter: (name = '***'::text) +``` + +## 特性约束 + +- 目前的SQL跟踪信息,基于正常的执行逻辑。执行失败的SQL,其跟踪信息不具有准确的参考价值。 +- 节点重启,可能导致该节点的数据丢失。 +- SQL语句执行完立即退出会话,可能会丢失该会话未刷新到系统表中的数据。 +- 通过GUC参数设置收集SQL语句的数量,如果超过阈值,新的SQL语句执行信息不会被收集。 +- 通过GUC参数设置单条SQL语句收集的锁事件详细信息的最大字节数,如果超过阈值,新的锁事件详细信息不会被收集。 +- 通过异步刷新方式刷新用户执行中的SQL信息,所以用户Query执行结束后,存在查询相关视图函数结果短暂时延。 +- 部分指标信息(行活动、Cache/IO、时间分布等)依赖于dbe_perf.statement视图收集,如果该视图对应记录数超过预定大小(依赖GUC:instr_unique_sql_count),则本特性可能不收集相关指标。 +- statement_history表相关函数以及视图中details字段为二进制格式,如果需要解析详细内容,请使用对应函数pg_catalog.statement_detail_decode(details, 'plaintext', true)。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/4-session-performance-diagnosis.md b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/4-session-performance-diagnosis.md new file mode 100644 index 00000000..e2b934d6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/4-session-performance-diagnosis.md @@ -0,0 +1,106 @@ +--- +title: Session性能诊断 +summary: Session性能诊断 +author: Guo Huan +date: 2022-05-07 +--- + +# Session性能诊断 + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +Session性能诊断提供给用户Session级别的性能问题诊断。 + +## 客户价值 + +- 查看最近用户Session最耗资源的事件。 +- 查看最近比较占资源的SQL把资源都消耗在哪些等待事件上。 +- 查看最近比较耗资源的Session把资源都花费在哪些等待事件上。 +- 查看最近最耗资源的用户的信息。 +- 查看过去Session相互阻塞的等待关系。 + +## 特性描述 + +Session性能诊断提供对当前系统所有活跃Session进行诊断的能力。由于实时采集所有活跃Session的指标对用户负载的影响加大,因此采取Session快照的技术对活跃Session的指标进行采样。 + +从采样中统计出活跃Session的统计指标,这些统计指标从客户端信息、执行开始、结束时间,SQL文本,等待事件,当前数据库对象等维度,反映活跃Session的基本信息,状态,持有的资源。 + +基于概率统计的活跃Session信息,可以帮助用户诊断系统中哪些Session消耗了更多的CPU、内存资源,哪些数据库对象是热对象,哪些SQL消耗了更多的关键事件资源等,从而定位出有问题Session,SQL,数据库设计。 + +Session采样数据分为两级,如图1所示: + +1. 第一级为实时信息,存储在内存中,展示最近几分钟的活跃Session信息,具有最高的精度; +2. 第二级为持久化历史信息,存储在磁盘文件中,展示过去很长一段时间的历史活跃Session信息,从内存数据中抽样而来,适合长时间跨度的统计分析。 + +**图 1** Session性能诊断原理 + + ![Session性能诊断原理](https://cdn-mogdb.enmotech.com/docs-media/mogdb/characteristic-description/session-performance-diagnosis-1.png) + +部分使用场景如下所示: + +1. 查看session之间的阻塞关系 + + ```sql + select sessionid, block_sessionid from pg_thread_wait_status; + ``` + +2. 采样blocking session信息 + + ```sql + select sessionid, block_sessionid from DBE_PERF.local_active_session; + ``` + +3. Final blocking session展示 + + ```sql + select sessionid, block_sessionid, final_block_sessionid from DBE_PERF.local_active_session; + ``` + +4. 最耗资源的wait event + + ```sql + SELECT s.type, s.event, t.count + FROM dbe_perf.wait_events s, ( + SELECT event, COUNT (*) + FROM dbe_perf.local_active_session + WHERE sample_time > now() - 5 / (24 * 60) + GROUP BY event)t WHERE s.event = t.event ORDER BY count DESC; + ``` + +5. 查看最近五分钟较耗资源的session把资源都花费在哪些event上 + + ```sql + SELECT sessionid, start_time, event, count + FROM ( + SELECT sessionid, start_time, event, COUNT(*) + FROM dbe_perf.local_active_session + WHERE sample_time > now() - 5 / (24 * 60) + GROUP BY sessionid, start_time, event) as t ORDER BY SUM(t.count) OVER \(PARTITION BY t. sessionid, start_time)DESC, t.event; + ``` + +6. 最近五分钟比较占资源的SQL把资源都消耗在哪些event上 + + ```sql + SELECT query_id, event, count + FROM ( + SELECT query_id, event, COUNT(*) + FROM dbe_perf.local_active_session + WHERE sample_time > now() - 5 / (24 * 60) + GROUP BY query_id, event) t ORDER BY SUM (t.count) OVER (PARTITION BY t.query_id ) DESC, t.event DESC; + ``` + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/5-system-kpi-aided-diagnosis.md b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/5-system-kpi-aided-diagnosis.md new file mode 100644 index 00000000..ad7223eb --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/5-system-kpi-aided-diagnosis.md @@ -0,0 +1,66 @@ +--- +title: 系统KPI辅助诊断 +summary: 系统KPI辅助诊断 +author: Guo Huan +date: 2022-05-07 +--- + +# 系统KPI辅助诊断 + +## 可获得性 + +本特性自MogDB 1.1.0 版本开始引入。 + +## 特性简介 + +KPI是内核组件或者整体性能关键指标的视图呈现,基于这些指标,用户可以了解到系统运行的实时或者历史状态。 + +## 客户价值 + +- 系统负载概要诊断 + + 系统负载异常(过载、失速、业务SLA)精准告警,系统负载精准画像。 + +- 系统时间模型概要诊断 + + Instance和Query级别时间模型细分,诊断Instance和Query性能问题根因。 + +- Query性能诊断 + + 数据库级Query概要信息,TopSQL,SQL CPU,IO消耗,执行计划,硬解析过多。 + +- 磁盘IO、索引、buffer性能问题 + +- 连接池,线程池异常 + +- Checkpoint,Redo(RTO)性能问题 + +- 系统I/O、LWLock、Waits性能问题诊断 + + 诊断60+模块,240+关键操作性能问题。 + +- 函数级性能看护诊断(GSTRACE),功能诊断 + + 50+存储和执行层函数trace。 + +## 特性描述 + +MogDB提供涵盖11大类,26个子类的KPI,包括:Instance、File、Object、Workload、Communication、Session、Thread、Cache IO、Lock、Wait Event、Cluster。 + +KPI指标内核的分布如图1所示。 + +**图 1** KPI指标内核分布 + + ![KPI指标内核分布](https://cdn-mogdb.enmotech.com/docs-media/mogdb/characteristic-description/system-kpi-aided-diagnosis.png) + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/fault-diagnosis.md b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/fault-diagnosis.md new file mode 100644 index 00000000..929458c8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/maintainability/fault-diagnosis.md @@ -0,0 +1,34 @@ +--- +title: 故障诊断 +summary: 故障诊断 +author: Zhang Cuiping +date: 2022-06-17 +--- + +# 故障诊断 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +为了快速定位故障、收集系统故障信息、导出故障数据,进而修复故障,MogDB 3.0增强了OM功能以及gstrace诊断能力。 + +## 客户价值 + +故障诊断能力的增强,可以方便研发人员及时修复故障,保证系统的正常运行。 + +## 特性描述 + +gs_check工具可以对场景检查结果进行差异比较,并输出差异分析报告,帮助用户快速定位问题。 + +gs_watch工具可监测MogDB进程,当发现进程崩溃时,自动触发调用gs_collector对系统状态进行收集,以便后期分析。 + +gs_gucquery工具可自动收集整理并导出GUC值,比较不同时刻GUC值的变化。 + +gstrace诊断能力增强。支持按模块名和方法名打开一个或多个component(模块)和function(方法)的trace项;提升代码中gstrace点数量,增强gstrace输出信息表达能力;支持新的对关键数据结构PGPROC和user session数据的导出;实现故障注入,包括系统调用报错模拟和变量内容攒写。 + +## 相关页面 + +[gs_check](../../reference-guide/tool-reference/server-tools/1-gs_check.md),[gs_gucquery](../../reference-guide/tool-reference/server-tools/gs_gucquery.md),[gstrace](../../reference-guide/tool-reference/tools-used-in-the-internal-system/16-gstrace.md),[gs_watch](../../reference-guide/tool-reference/server-tools/gs_watch.md) diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/middleware/deploying-a-distributed-database-using-kubernetes.md b/product/zh/docs-mogdb/v3.1/characteristic-description/middleware/deploying-a-distributed-database-using-kubernetes.md new file mode 100644 index 00000000..5a55fbae --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/middleware/deploying-a-distributed-database-using-kubernetes.md @@ -0,0 +1,36 @@ +--- +title: 使用kubernetes部署分布式数据库 +summary: 使用kubernetes部署分布式数据库 +author: Guo Huan +date: 2022-05-10 +--- + +# 使用kubernetes部署分布式数据库 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +一键式部署分布式数据库。 + +## 客户价值 + +快速完成分布式数据库搭建,验证和使用分布式能力。 + +## 特性描述 + +通过patroni实现计划内switchover和故障场景自动failover, 通过haproxy实现MogDB主备节点读写负载均衡,通过shardingsphere实现分布式能力,所有功能打包至镜像并提供一键式部署脚本。 + +## 特性增强 + +无。 + +## 特性约束 + +仅支持centos或openEuler操作系统。 + +## 依赖关系 + +shardingsphere、patroni、haproxy。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/middleware/distributed-database-capability.md b/product/zh/docs-mogdb/v3.1/characteristic-description/middleware/distributed-database-capability.md new file mode 100644 index 00000000..a1fec593 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/middleware/distributed-database-capability.md @@ -0,0 +1,36 @@ +--- +title: 分布式数据库能力 +summary: 分布式数据库能力 +author: Guo Huan +date: 2022-05-10 +--- + +# 分布式数据库能力 + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +基于分布式中间件shardingsphere使MogDB具备分布式数据库能力。使用16个鲲鹏920(128核)节点组网(1\*shardingsphere-proxy、7\*shardingsphere-jdbc、8\*MogDB)时,完美sharding性能>1000万tpmc。 + +## 客户价值 + +通过中间件构建逻辑上无资源限制的分布式数据库。 + +## 特性描述 + +通过shardingsphere中间件的分库分表能力,使多个MogDB数据库可以在逻辑上组成一个更大的数据库,同时具备分布式事务和弹性伸缩的能力,使用方式与MogDB数据库并无不同。 + +## 特性增强 + +无。 + +## 特性约束 + +无。 + +## 依赖关系 + +shardingsphere中间件。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/tool-chain/mogdb-client-tool-datastudio.md b/product/zh/docs-mogdb/v3.1/characteristic-description/tool-chain/mogdb-client-tool-datastudio.md new file mode 100644 index 00000000..f8f89359 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/tool-chain/mogdb-client-tool-datastudio.md @@ -0,0 +1,57 @@ +--- +title: MogDB客户端工具DataStudio +summary: MogDB客户端工具DataStudio +author: Guo Huan +date: 2022-05-10 +--- + +# MogDB客户端工具DataStudio + +## 可获得性 + +DataStudio可在openGauss官网获取安装包,或在gitee上获取源码自行编译。 + +## 特性简介 + +DataStudio是面向开发人员和数据库管理员的通用集成开发环境。它简化了MogDB数据库的开发和管理。 + +DataStudio允许数据库开发人员: + +- 管理和创建数据库对象 +- 执行SQL语句或SQL脚本 +- 编辑和执行PL/SQL语句 +- 导入和导出表格数据 + +## 客户价值 + +Data Studio作为一款配套MogDB数据库使用的客户端软件,辅助数据库开发人员便捷地构建应用程序,以图形化界面形式提供数据库关键特性。 降低数据库的使用门槛,提高用户的使用粘性。 + +## 特性描述 + +用户在Windows环境上,使用DataStudio远程连接MogDB,并在DataStudio上对MogDB进行操作。例如: + +- 图形化的数据库客户端集成开发环境,允许连接MogDB数据库 +- 允许数据库开发者可以高效的进行SQL开发 +- 管理/创建数据库对象(数据库、模式、函数、存储过程、表、序列、列、索引、约束、视图、用户/角色和表空间) +- 执行SQL语句或SQL脚本 +- 创建和执行存储过程 +- 表数据增、删、改、查 +- 导入/导出表数据 +- 显示DDL、导出DDL、导出DDL和数据 +- 导入/导出连接信息 +- SQL格式化 +- SQL执行历史记录 +- 显示执行计划、ER图 + +## 特性增强 + +无。 + +## 特性约束 + +- 支持windows系统 +- 支持jdk11及以上版本 + +## 依赖关系 + +当前只支持openGauss/MogDB \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/characteristic-description/tool-chain/mysql-to-mogdb-migration-tool-chameleon.md b/product/zh/docs-mogdb/v3.1/characteristic-description/tool-chain/mysql-to-mogdb-migration-tool-chameleon.md new file mode 100644 index 00000000..bc8797f0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/characteristic-description/tool-chain/mysql-to-mogdb-migration-tool-chameleon.md @@ -0,0 +1,37 @@ +--- +title: MySQL->MogDB迁移工具chameleon +summary: MySQL->MogDB迁移工具chameleon +author: Guo Huan +date: 2022-05-10 +--- + +# MySQL->MogDB迁移工具chameleon + +## 可获得性 + +本特性自MogDB 3.0.0版本开始引入。 + +## 特性简介 + +chameleon工具是一个基于Python语言的MySQL到MogDB的实时复制工具。该工具提供了初始全量数据的复制以及增量数据的实时复制能力,可实现数据从MySQL迁移至MogDB。对于数据的全量和增量迁移,支持MySQL中各种数据类型的迁移,同时对于MySQL中的浮点数据类型,包括decimal、dec、numeric、float、float4、float8、real、double、double precision、fixed数据类型,可保证迁移后数据精度不丢失。 + +## 客户价值 + +通过使用chameleon工具,可完成数据从MySQL搬迁至MogDB数据库。 + +## 特性描述 + +chameleon工具提供数据全量和增量复制功能,使得数据可以从MySQL迁移至MogDB数据库。对于数据的全量和增量迁移,chameleon工具中存储了MySQL数据类型与MogDB数据类型之间的映射关系,可支持MySQL中各种数据类型的迁移。特别地,对于MySQL中的浮点数据类型,包括decimal、dec、numeric、float、float4、float8、real、double、double precision、fixed数据类型,若数据类型中显示指定或默认含有精度,将转化为MogDB中的numeric[p, s]类型;若数据类型中未显示指定精度,将转化为MogDB中的numeric数据类型,基于此,可保证离线迁移和在线迁移后数据精度不丢失。 + +## 特性增强 + +无。 + +## 特性约束 + +- 支持MySQL 5.7版本。 +- 对于数据类型映射后仍存在不兼容的情形,将导致表数据迁移失败,但不会终止后续的数据离线迁移过程。 + +## 依赖关系 + +无。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/1-core-dump-occurs-due-to-full-disk-space.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/1-core-dump-occurs-due-to-full-disk-space.md new file mode 100644 index 00000000..758fefdf --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/1-core-dump-occurs-due-to-full-disk-space.md @@ -0,0 +1,22 @@ +--- +title: 磁盘满故障引起的core问题 +summary: 磁盘满故障引起的core问题 +author: Guo Huan +date: 2021-05-24 +--- + +# 磁盘满故障引起的core问题 + +## 问题现象 + +TPCC运行时,注入磁盘满故障,数据库进程mogdb core掉,如下图所示。 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/core-dump-occurs-due-to-full-disk-space.png) + +## 原因分析 + +数据库本身机制,在磁盘满时,xlog日志无法进行写入,通过panic日志退出程序。 + +## 处理办法 + +外部监控磁盘使用状况,定时进行清理磁盘。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/2-core-dump-occurs-due-to-incorrect-settings-of-guc-parameter-log-directory.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/2-core-dump-occurs-due-to-incorrect-settings-of-guc-parameter-log-directory.md new file mode 100644 index 00000000..25cd64b7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/2-core-dump-occurs-due-to-incorrect-settings-of-guc-parameter-log-directory.md @@ -0,0 +1,20 @@ +--- +title: GUC参数log_directory设置不正确引起的core问题 +summary: GUC参数log_directory设置不正确引起的core问题 +author: Guo Huan +date: 2021-05-24 +--- + +# GUC参数log_directory设置不正确引起的core问题 + +## 问题现象 + +数据库进程拉起后出现coredump,日志无内容。 + +## 原因分析 + +GUC参数log_directory设置的路径不可读取或无访问权限,数据库在启动过程中进行校验失败,通过panic日志退出程序。 + +## 处理办法 + +GUC参数log_directory设置为合法路径,具体请参考[log_directory](../../../reference-guide/guc-parameters/10-error-reporting-and-logging/1-logging-destination.md#log_directory)。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/3-core-dump-occurs-when-removeipc-is-enabled.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/3-core-dump-occurs-when-removeipc-is-enabled.md new file mode 100644 index 00000000..724b088a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/3-core-dump-occurs-when-removeipc-is-enabled.md @@ -0,0 +1,24 @@ +--- +title: 开启RemoveIPC引起的core问题 +summary: 开启RemoveIPC引起的core问题 +author: Guo Huan +date: 2021-05-24 +--- + +# 开启RemoveIPC引起的core问题 + +## 问题现象 + +操作系统配置中RemoveIPC参数设置为yes,数据库运行过程中出现宕机,并显示如下日志消息。 + +``` +FATAL: semctl(1463124609, 3, SETVAL, 0) failed: Invalid argument +``` + +## 原因分析 + +当RemoveIPC参数设置为yes时,操作系统会在对应用户退出时删除IPC资源(共享内存和信号量),从而使得MogDB服务器使用的IPC资源被清理,引发数据库宕机。 + +## 处理分析 + +设置RemoveIPC参数为no。设置方法请参考《安装指南》中“[操作系统配置](../../../installation-guide/installation-preparation/os-configuration.md)”章节。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/4-core-dump-occurs-after-installation-on-x86.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/4-core-dump-occurs-after-installation-on-x86.md new file mode 100644 index 00000000..e717f74e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/1-core-fault-locating/4-core-dump-occurs-after-installation-on-x86.md @@ -0,0 +1,26 @@ +--- +title: x86下安装完成后发生coredump +summary: x86下安装完成后发生coredump +author: Guo Huan +date: 2021-12-09 +--- + +# x86下安装完成后发生coredump + +## 问题现象 + +x86架构下安装MogDB完成后发生coredump,出现如下报错 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/core-dump-occurs-after-installation-on-x86-1.png) + +## 原因分析 + +x86架构不包括rdtscp指令,常见于在本地windows系统上,虚拟化安装Linux服务器,但虚拟化版本太低,部署MogDB启动失败。 + +## 处理办法 + +使用`lscpu | grep rdtscp`查看是否支持rdtscp指令集 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/administrator-guide/core-dump-occurs-after-installation-on-x86-2.png) + +可以通过主机的管理侧设置开启支持该指令集。云主机CPU模式,设置为host-passthrough,重新reboot。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/10-disk-space-usage-reaches-the-threshold.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/10-disk-space-usage-reaches-the-threshold.md new file mode 100644 index 00000000..2bb6ec7a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/10-disk-space-usage-reaches-the-threshold.md @@ -0,0 +1,58 @@ +--- +title: 磁盘空间达到阈值,数据库只读 +summary: 磁盘空间达到阈值,数据库只读 +author: Guo Huan +date: 2021-05-24 +--- + +# 磁盘空间达到阈值,数据库只读 + +## 问题现象 + +执行非只读SQL时报错如下。 + +``` +ERROR: cannot execute %s in a read-only transaction. +``` + +或者运行中部分非只读SQL(insert、update、create table as、create index、alter table 及copy from等)时报错。 + +``` +canceling statement due to default_transaction_read_only is on. +``` + +## 原因分析 + +磁盘空间达到阈值后,设置数据库只读,只允许只读语句执行。 + +## 处理办法 + +1. 使用maintenance模式连接数据库,以下两种方法均可。 + + - 方式一 + + ```bash + gsql -d mogdb -p 8000 -r -m + ``` + + - 方式二 + + ```bash + gsql -d mogdb -p 8000 -r + ``` + + 连接成功后,执行如下命令: + + ```bash + set xc_maintenance_mode=on; + ``` + +2. 使用DROP/TRUNCATE语句删除当前不再使用的用户表,直至磁盘空间使用率小于设定的阈值。 + + 删除用户表只能暂时缓解磁盘空间不足的问题,建议尽早通过扩容解决磁盘空间不足的问题。 + +3. 使用系统用户omm设置数据库只读模式关闭。 + + ```bash + gs_guc reload -D /mogdb/data/dbnode -c "default_transaction_read_only=off" + ``` diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/11-slow-response-to-a-query-statement.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/11-slow-response-to-a-query-statement.md new file mode 100644 index 00000000..869cde7a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/11-slow-response-to-a-query-statement.md @@ -0,0 +1,48 @@ +--- +title: 分析查询语句长时间运行的问题 +summary: 分析查询语句长时间运行的问题 +author: Guo Huan +date: 2021-05-24 +--- + +# 分析查询语句长时间运行的问题 + +## 问题现象 + +系统中部分查询语句运行时间过长。 + +## 原因分析 + +- 查询语句较为复杂,需要长时间运行。 +- 查询语句阻塞。 + +## 处理办法 + +1. 以操作系统用户omm登录主机。 + +2. 使用如下命令连接数据库。 + + ```bash + gsql -d postgres -p 8000 + ``` + + postgres为需要连接的数据库名称,8000为端口号。 + +3. 查看系统中长时间运行的查询语句。 + + ```sql + SELECT timestampdiff(minutes, query_start, current_timestamp) AS runtime, datname, usename, query FROM pg_stat_activity WHERE state != 'idle' ORDER BY 1 desc; + ``` + + 查询会返回按执行时间长短从大到小排列的查询语句列表。第一条结果就是当前系统中执行时间长的查询语句。 + + 如果当前系统较为繁忙,可以使用[TIMESTAMPDIFF](../../reference-guide/functions-and-operators/8-date-and-time-processing-functions-and-operators.md)函数通过限制current_timestamp和query_start大于某一阈值查看执行时间超过此阈值的查询语句。timestampdiff的第一个参数为时间差单位。例如,执行超过2分钟的查询语句可以通过如下语句查询。 + + ```sql + SELECT query FROM pg_stat_activity WHERE timestampdiff(minutes, query_start, current_timestamp) > 2; + ``` + +4. 分析长时间运行的查询语句状态。 + + - 如果查询语句处于正常状态,则等待其执行完毕。 + - 如果查询语句阻塞,请参见[分析查询语句是否被阻塞处理](14-analyzing-whether-a-query-statement-is-blocked.md)。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/12-analyzing-the-status-of-a-query-statement.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/12-analyzing-the-status-of-a-query-statement.md new file mode 100644 index 00000000..3c33466a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/12-analyzing-the-status-of-a-query-statement.md @@ -0,0 +1,57 @@ +--- +title: 分析查询语句运行状态 +summary: 分析查询语句运行状态 +author: Guo Huan +date: 2021-05-24 +--- + +# 分析查询语句运行状态 + +## 问题现象 + +系统中部分查询语句运行时间过长,需要分析查询语句的运行状态。 + +## 处理办法 + +1. 以操作系统用户omm登录主机。 + +2. 使用如下命令连接数据库。 + + ```bash + gsql -d postgres -p 8000 + ``` + + postgres为需要连接的数据库名称,8000为端口号。 + +3. 设置参数track_activities为on。 + + ```sql + SET track_activities = on; + ``` + + 当此参数为on时,数据库系统才会收集当前活动查询的运行信息。 + +4. 查看正在运行的查询语句。以查看视图pg_stat_activity为例。 + + ```sql + SELECT datname, usename, state, query FROM pg_stat_activity; + datname | usename | state | query + ----------+---------+--------+------- + mogdb | omm | idle | + mogdb | omm | active | + (2 rows) + ``` + + 如果state字段显示为idle,则表明此连接处于空闲,等待用户输入命令。 如果仅需要查看非空闲的查询语句,则使用如下命令查看。 + + ```sql + SELECT datname, usename, state, query FROM pg_stat_activity WHERE state != 'idle'; + ``` + +5. 分析查询语句为活跃状态还是阻塞状态。通过如下命令查看当前处于阻塞状态的查询语句。 + + ```sql + SELECT datname, usename, state, query FROM pg_stat_activity WHERE waiting = true; + ``` + + 查询结果中包含了当前被阻塞的查询语句,该查询语句所请求的锁资源可能被其他会 话持有,正在等待持有会话释放锁资源。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/13-forcibly-terminating-a-session.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/13-forcibly-terminating-a-session.md new file mode 100644 index 00000000..d02b0cd9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/13-forcibly-terminating-a-session.md @@ -0,0 +1,62 @@ +--- +title: 强制结束指定的问题会话 +summary: 强制结束指定的问题会话 +author: Guo Huan +date: 2021-05-24 +--- + +# 强制结束指定的问题会话 + +## 问题现象 + +有些情况下,为了使系统继续提供服务,管理员需要强制结束有问题的会话。 + +## 处理办法 + +1. 以操作系统用户omm登录主机。 + +2. 使用如下命令连接数据库。 + + ```bash + gsql -d mogdb -p 8000 + ``` + + mogdb为需要连接的数据库名称,8000为端口号。 + +3. 从当前活动会话视图查找问题会话的线程ID。 + + ```sql + SELECT datid, pid, state, query FROM pg_stat_activity; + ``` + + 显示类似如下信息,其中pid的值即为该会话的线程ID。 + + ``` + datid | pid | state | query + -------+-----------------+--------+------ + 13205 | 139834762094352 | active | + 13205 | 139834759993104 | idle | + (2 rows) + ``` + +4. 根据线程ID结束会话。 + + ```sql + SELECT pg_terminate_backend(139834762094352); + ``` + + 显示类似如下信息,表示结束会话成功。 + + ``` + pg_terminate_backend + --------------------- + t + (1 row) + ``` + + 显示类似如下信息,表示用户正在尝试结束当前会话,此时仅会重连会话,而不是结束会话。 + + ``` + FATAL: terminating connection due to administrator command + FATAL: terminating connection due to administrator command The connection to the server was lost. Attempting reset: Succeeded. + ``` diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/14-analyzing-whether-a-query-statement-is-blocked.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/14-analyzing-whether-a-query-statement-is-blocked.md new file mode 100644 index 00000000..350cad56 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/14-analyzing-whether-a-query-statement-is-blocked.md @@ -0,0 +1,56 @@ +--- +title: 分析查询语句是否被阻塞 +summary: 分析查询语句是否被阻塞 +author: Guo Huan +date: 2021-05-24 +--- + +# 分析查询语句是否被阻塞 + +## 问题现象 + +数据库系统运行时,在某些业务场景下,查询语句会被阻塞,导致语句运行时间过长。 + +## 原因分析 + +查询语句需要通过加锁来保护其要访问的数据对象。当要进行加锁时发现要访问的数据对象已经被其他会话加锁,则查询语句会被阻塞,等待其他会话完成操作并释放锁资源。这些需要加锁访问的数据对象主要包括表、元组等。 + +## 处理办法 + +1. 以操作系统用户omm登录主机。 + +2. 使用如下命令连接数据库。 + + ```bash + gsql -d mogdb -p 8000 + ``` + + mogdb为需要连接的数据库名称,8000为端口号。 + +3. 从当前活动会话视图查找问题会话的线程ID。 + + ```sql + SELECT w.query AS waiting_query, w.pid AS w_pid, w.usename AS w_user, l.query AS locking_query, l.pid AS l_pid, l.usename AS l_user, t.schemaname || '.' || t.relname AS tablename FROM pg_stat_activity w JOIN pg_locks l1 ON w.pid = l1.pid AND NOT l1.granted JOIN pg_locks l2 ON l1.relation = l2.relation AND l2.granted JOIN pg_stat_activity l ON l2.pid = l.pid JOIN pg_stat_user_tables t ON l1.relation = t.relid WHERE w.waiting = true; + ``` + +4. 根据线程ID结束会话。 + + ```sql + SELECT pg_terminate_backend(139834762094352); + ``` + + 显示类似如下信息,表示结束会话成功。 + + ``` + pg_terminate_backend + --------------------- + t + (1 row) + ``` + + 显示类似如下信息,表示用户正在尝试结束当前会话,此时仅会重连会话,而不是结束会话。 + + ``` + FATAL: terminating connection due to administrator command + FATAL: terminating connection due to administrator command The connection to the server was lost. Attempting reset: Succeeded. + ``` diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/15-low-query-efficiency.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/15-low-query-efficiency.md new file mode 100644 index 00000000..63fcf362 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/15-low-query-efficiency.md @@ -0,0 +1,32 @@ +--- +title: 分析查询效率异常降低的问题 +summary: 分析查询效率异常降低的问题 +author: Guo Huan +date: 2021-05-24 +--- + +# 分析查询效率异常降低的问题 + +## 问题现象 + +通常在几十毫秒内完成的查询,有时会突然需要几秒的时间完成;而通常需要几秒完成的查询,有时需要半小时才能完成。 + +## 处理办法 + +通过下列的操作步骤,分析查询效率异常降低的原因。 + +1. 使用analyze命令分析数据库。 + + 使用analyze命令会更新所有表中数据大小以及属性等相关统计信息,建议在作业压力较小时执行。如果此命令执行后性能恢复或者有所提升,则表明autovacuum未能很好的完成它的工作,有待进一步分析。 + +2. 检查查询语句是否返回了多余的数据信息。 + + 例如,如果查询语句先查询一个表中所有的记录,而只用到结果中的前10条记录。对于包含50条记录的表,查询速度较快;但是,当表中包含的记录数达到50000条,查询效率将会有所下降。 如果业务应用中存在只需要部分数据信息,但是查询语句却是返回所有信息的情况,建议修改查询语句,增加LIMIT子句来限制返回的记录数。这样使数据库优化器有了一定的优化空间,一定程度上会提升查询效率。 + +3. 检查查询语句单独运行时是否仍然较慢。 + + 尝试在数据库没有其他查询或查询较少的时候运行查询语句,并观察运行效率。如果效率较高,则说明可能是由于之前运行数据库系统的主机负载过大导致查询低效。此外,还可能是由于执行计划比较低效,但是由于主机硬件较快使得查询效率较高。 + +4. 检查重复相同查询语句的执行效率。 + + 查询效率低的一个重要原因是查询所需信息没有缓存在内存中,这可能是由于内存资源紧张,导致缓存信息被其他查询处理覆盖。重复执行相同的查询语句,如果后续执行的查询语句效率提升,则可能是由于上述原因导致。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/16-lock-wait-timeout-is-displayed.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/16-lock-wait-timeout-is-displayed.md new file mode 100644 index 00000000..06e30c47 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/16-lock-wait-timeout-is-displayed.md @@ -0,0 +1,25 @@ +--- +title: 执行SQL语句时,提示Lock wait timeout +summary: 执行SQL语句时,提示Lock wait timeout +author: Guo Huan +date: 2021-05-24 +--- + +# 执行SQL语句时,提示Lock wait timeout + +## 问题现象 + +执行SQL语句时,提示“Lock wait timeout”。 + +``` +ERROR: Lock wait timeout: thread 140533638080272 waiting for ShareLock on relation 16409 of database 13218 after 1200000.122 ms ERROR: Lock wait timeout: thread 140533638080272 waiting for AccessExclusiveLock on relation 16409 of database 13218 after 1200000.193 ms +``` + +## 原因分析 + +数据库中存在锁等待超时现象。 + +## 处理办法 + +- 数据库在识别此类错误后,会自动进行重跑,重跑次数可以使用max_query_retry_times控制。 +- 需要分析锁超时的原因,查看系统表pg_locks,pg_stat_activity可以找出超时的SQL语句。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/17-table-size-does-not-change.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/17-table-size-does-not-change.md new file mode 100644 index 00000000..7a7c328e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/17-table-size-does-not-change.md @@ -0,0 +1,39 @@ +--- +title: VACUUM FULL一张表后,表文件大小无变化 +summary: VACUUM FULL一张表后,表文件大小无变化 +author: Guo Huan +date: 2021-05-24 +--- + +# VACUUM FULL一张表后,表文件大小无变化 + +## 问题现象 + +使用VACUUM FULL命令对一张表进行清理,清理完成后表大小和清理前一样大。 + +## 原因分析 + +假定该表的名称为table_name,对于该现象可能有以下两种原因: + +- table_name表本身没有delete过数据,使用VACUUM FULL table_name后无需清理delete的数据。因此表大小清理前后一样大。 +- 在执行VACUUM FULL table_name时有并发的事务存在,可能会导致VACUUM FULL跳过清理最近删除的数据,导致清理不完全。 + +## 处理办法 + +对于第二种可能原因,有如下两种处理方法: + +- 如果在VACUUM FULL时有并发的事务存在,此时需要等待所有事务结束,再次执行VACUUM FULL命令对该表进行清理。 + +- 如果使用上面的方法清理后,表文件大小仍然无变化,确认无业务操作后,使用以下SQL查询活跃事务列表状态: + + ```sql + select txid_current(); + ``` + + 使用该SQL可以查询当前的事务XID。再使用以下命令查看活跃事务列表: + + ```sql + select txid_current_snapshot(); + ``` + + 如果发现活跃事务列表中有XID比当前的事务XID小时,停止数据库再启动数据库,再次使用VACUUM FULL命令对该表进行清理。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/18-an-error-is-reported-when-the-table-partition-is-modified.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/18-an-error-is-reported-when-the-table-partition-is-modified.md new file mode 100644 index 00000000..9f172c49 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/18-an-error-is-reported-when-the-table-partition-is-modified.md @@ -0,0 +1,46 @@ +--- +title: 执行修改表分区操作时报错 +summary: 执行修改表分区操作时报错 +author: Guo Huan +date: 2021-05-24 +--- + +# 执行修改表分区操作时报错 + +## 问题现象 + +执行ALTER TABLE PARTITION时,报错如下。 + +``` +ERROR:start value of partition "XX" NOT EQUAL up-boundary of last partition. +``` + +## 原因分析 + +在同一条ALTER TABLE PARTITION语句中,既存在DROP PARTITION又存在ADD PARTITION时,无论它们在语句中的顺序是什么,MogDB总会先执行DROP PARTITION再执行ADD PARTITION。执行完DROP PARTITION删除末尾分区后,再执行ADD PARTITION操作会出现分区间隙,导致报错。 + +## 处理办法 + +为防止出现分区间隙,需要将ADD PARTITION的START值前移。 示例如下。 + +```sql +--创建分区表partitiontest。 +MogDB=# CREATE TABLE partitiontest +( +c_int integer, +c_time TIMESTAMP WITHOUT TIME ZONE +) +PARTITION BY range (c_int) +( +partition p1 start(100)end(108), +partition p2 start(108)end(120) +); +--使用如下两种语句会发生报错: +MogDB=# ALTER TABLE partitiontest ADD PARTITION p3 start(120)end(130), DROP PARTITION p2; +ERROR: start value of partition "p3" NOT EQUAL up-boundary of last partition. +MogDB=# ALTER TABLE partitiontest DROP PARTITION p2,ADD PARTITION p3 start(120)end(130); +ERROR: start value of partition "p3" NOT EQUAL up-boundary of last partition. +--可以修改语句为: +MogDB=# ALTER TABLE partitiontest ADD PARTITION p3 start(108)end(130), DROP PARTITION p2; +MogDB=# ALTER TABLE partitiontest DROP PARTITION p2,ADD PARTITION p3 start(108)end(130); +``` diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/19-different-data-is-displayed.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/19-different-data-is-displayed.md new file mode 100644 index 00000000..545900e8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/19-different-data-is-displayed.md @@ -0,0 +1,32 @@ +--- +title: 不同用户查询同表显示数据不同 +summary: 不同用户查询同表显示数据不同 +author: Guo Huan +date: 2021-05-24 +--- + +# 不同用户查询同表显示数据不同 + +## 问题现象 + +2个用户登录相同数据库human_resource,同样执行如下查询语句,查询同一张表areas时,查询结果却不一致。 + +```sql +select count(*) from areas; +``` + +## 原因分析 + +1. 检查同名表是否是同一张表。在关系型数据库中,确定一张表通常需要3个因素:database、schema、table。从问题现象描述看,database、table已经确定,分别是human_resource、areas。 +2. 检查同名表的schema是否一致。使用omm、user01分别登录发现,search_path依次是public和“$user”。omm作为数据库管理员,默认不会创建omm同名的schema,即不指定schema的情况下所有表都会建在public下。而对于普通用户如user01,则会在创建用户时,默认创建同名的schema,即不指定schema时表都会创建在user01的schema下。 +3. 如果最终判断是同一张表,存在不同用户访问数据不同情况,则需要进一步判断当前该表中对象针对不同的用户是否存在不同的访问策略。 + +## 处理办法 + +- 对于不同schema下同名表的查询,在查询表时加上schema引用。格式如下。 + + ``` + schema.table + ``` + +- 对于不同访问策略造成对同一表查询结果不同时,可以通过查询pg_rlspolicy系统表来确认具体的访问准则。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/2-when-the-tpcc-is-running.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/2-when-the-tpcc-is-running.md new file mode 100644 index 00000000..fe49110d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/2-when-the-tpcc-is-running.md @@ -0,0 +1,20 @@ +--- +title: TPCC运行时,注入磁盘满故障,TPCC卡住的问题 +summary: TPCC运行时,注入磁盘满故障,TPCC卡住的问题 +author: Guo Huan +date: 2021-05-24 +--- + +# TPCC运行时,注入磁盘满故障,TPCC卡住的问题 + +## 问题现象 + +TPCC运行时,注入磁盘满故障,TPCC卡住,故障消除后,TPCC自动续跑。 + +## 原因分析 + +数据库本身机制,在性能日志(gs_profile)所在磁盘满时,导致无法写入而陷入无限等待,表现为TPCC卡住。磁盘满故障消除后,性能日志能正常写入,TPCC恢复正常。 + +## 处理分析 + +外部监控磁盘使用状况,定时进行清理磁盘。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/20-when-a-user-specifies-only-an-index-name.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/20-when-a-user-specifies-only-an-index-name.md new file mode 100644 index 00000000..d73f9b9f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/20-when-a-user-specifies-only-an-index-name.md @@ -0,0 +1,47 @@ +--- +title: 修改索引时只调用索引名提示索引不存在 +summary: 修改索引时只调用索引名提示索引不存在 +author: Guo Huan +date: 2021-05-24 +--- + +# 修改索引时只调用索引名提示索引不存在 + +## 问题现象 + +修改索引时只调用索引名提示索引不存在。举例如下。 + +```sql +--创建分区表索引HR_staffS_p1_index1,不指定索引分区的名称。 +CREATE INDEX HR_staffS_p1_index1 ON HR.staffS_p1 (staff_ID) LOCAL; +--创建分区索引HR_staffS_p1_index2,并指定索引分区的名称。 +CREATE INDEX HR_staffS_p1_index2 ON HR.staffS_p1 (staff_ID) LOCAL +( +PARTITION staff_ID1_index, +PARTITION staff_ID2_index TABLESPACE example3, +PARTITION staff_ID3_index TABLESPACE example4 +) TABLESPACE example; +--修改索引分区staff_ID2_index的表空间为example1,提示索引不存在。 +ALTER INDEX HR_staffS_p1_index2 MOVE PARTITION staff_ID2_index TABLESPACE example1; +``` + +## 原因分析 + +推测是当前模式是public模式,而不是hr模式,导致检索不到该索引。 + +```sql +--执行如下命令验证推测,发现调用成功。 +ALTER INDEX hr.HR_staffS_p1_index2 MOVE PARTITION staff_ID2_index TABLESPACE example1; +--修改当前会话的schema为hr。 +ALTER SESSION SET CURRENT_SCHEMA TO hr; +--执行如下命令修改索引,即可执行成功。 +ALTER INDEX HR_staffS_p1_index2 MOVE PARTITION staff_ID2_index TABLESPACE example1; +``` + +## 处理办法 + +在操作表、索引、视图时加上schema引用,格式如下。 + +``` +schema.table +``` diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/21-reindexing-fails.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/21-reindexing-fails.md new file mode 100644 index 00000000..f7f671de --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/21-reindexing-fails.md @@ -0,0 +1,29 @@ +--- +title: 重建索引失败 +summary: 重建索引失败 +author: Guo Huan +date: 2021-05-24 +--- + +# 重建索引失败 + +## 问题现象 + +当Desc表的索引出现损坏时,无法进行一系列操作,可能的报错信息如下。 + +``` +index \"%s\" contains corrupted page at block + %u" ,RelationGetRelationName(rel),BufferGetBlockNumber(buf), please reindex it. +``` + +## 原因分析 + +在实际操作中,索引会由于软件问题或者硬件问题引起崩溃。例如,当索引分裂完而磁盘空间不足、出现页面损坏等问题时,会导致索引损坏。 + +## 处理办法 + +如果此表是以pg_cudesc_xxxxx_index进行命名则为列存表,则说明desc表的索引表损坏。通过desc表的索引表表名,找到对应主表的oid和表,执行如下语句重建表的索引。 + +``` +REINDEX INTERNAL TABLE name; +``` diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/22-an-error-occurs-during-integer-conversion.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/22-an-error-occurs-during-integer-conversion.md new file mode 100644 index 00000000..fb9c6c7e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/22-an-error-occurs-during-integer-conversion.md @@ -0,0 +1,24 @@ +--- +title: 业务运行时整数转换错 +summary: 业务运行时整数转换错 +author: Guo Huan +date: 2021-05-24 +--- + +# 业务运行时整数转换错 + +## 问题现象 + +在转换整数时报错如下。 + +``` +Invalid input syntax for integer: "13." +``` + +## 原因分析 + +部分数据类型不能转换成目标数据类型。 + +## 处理办法 + +逐步缩小SQL范围确定不能转换的数据类型。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/23-too-many-clients-already.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/23-too-many-clients-already.md new file mode 100644 index 00000000..3a2abb37 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/23-too-many-clients-already.md @@ -0,0 +1,50 @@ +--- +title: 高并发报错“too many clients already”或无法创建线程 +summary: 高并发报错“too many clients already”或无法创建线程Concurrency Scenarios +author: Guo Huan +date: 2021-05-24 +--- + +# 高并发报错“too many clients already”或无法创建线程 + +## 问题现象 + +高并发执行SQL,报错“sorry, too many clients already”;或报无法创建线程、无法fork进程等错误。 + +## 原因分析 + +该类报错是由于操作系统线程资源不足引起,查看操作系统ulimit -u,如果过小(例如小于32768),则基本可以判断是操作系统限制引起的。 + +## 处理办法 + +通过“ulimit -u”命令查看操作系统max user processes的值。 + +``` +[root@MogDB36 mnt]# ulimit -u +unlimited +``` + +按如下简易公式计算需要设置的最小值。 + +``` +value=max(32768,实例数目*8192) +``` + +其中实例数目指本节点所有实例总数。 + +设置最小值方法为,修改/etc/security/limits.conf,追加如下两行: + +``` +* hard nproc [value] +* soft nproc [value] +``` + +对于不同操作系统修改方式略有不同,centos6以上版本可以修改/etc/security/ limits.d/90-nofile.conf文件,方法同上。 + +另外,也可以直接通过如下命令设置,但OS重启会失效,可以添加到全局环境变量/etc/profile文件中使其生效。 + +``` +ulimit -u [values] +``` + +在大并发模式下,建议开启线程池,使数据库内部的线程资源受控。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/24-b-tree-index-faults.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/24-b-tree-index-faults.md new file mode 100644 index 00000000..98882037 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/24-b-tree-index-faults.md @@ -0,0 +1,68 @@ +--- +title: btree索引故障情况下应对策略 +summary: btree索引故障情况下应对策略 +author: Guo Huan +date: 2021-05-24 +--- + +# btree索引故障情况下应对策略 + +## 问题现象 + +偶发索引丢失错误,报错如下。 + +``` +ERROR: index 'xxxx_index' contains unexpected zero page +或 +ERROR: index 'pg_xxxx_index' contains unexpected zero page +或 +ERROR: compressed data is corrupt +``` + +## 原因分析 + +该类错误是因为索引发生故障导致的,可能引发故障的原因如下: + +- 由于软件bug或者硬件原因导致的索引不再可用。 +- 索引包含许多空的页面或者几乎为空的页面。 +- 并发执行DDL过程中,发生了网络闪断故障 +- 创建并发索引时失败,遗留了一个失效的索引,这样的索引无法被使用。 +- 执行DDL或者DML操作时,网络出现故障。 + +## 处理办法 + +执行REINDEX命令进行索引重建。 + +1. 以操作系统用户omm登录主机。 + +2. 使用如下命令连接数据库。 + + ```bash + gsql -d mogdb -p 8000 -r + ``` + +3. 重建索引。 + + - 如果进行DDL或DML操作时,因软硬件故障导致索引问题,请执行如下命令重建表索引。 + + ``` + REINDEX TABLE tablename; + ``` + + - 如果错误中提示是xxxx_index,其中xxxx代表用户表名。请执行如下命令之一重建表的索引。 + + ``` + REINDEX INDEX indexname; + ``` + + 或者 + + ``` + REINDEX TABLE tablename; + ``` + + - 如果错误中提示pg_xxxx_index,说明是系统表索引存在问题。请执行如下命令重建表索引。 + + ``` + REINDEX SYSTEM databasename; + ``` diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/3-standby-node-in-the-need-repair-state.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/3-standby-node-in-the-need-repair-state.md new file mode 100644 index 00000000..7722e206 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/3-standby-node-in-the-need-repair-state.md @@ -0,0 +1,20 @@ +--- +title: 备机处于need repair(WAL)状态问题 +summary: 备机处于need repair(WAL)状态问题 +author: Guo Huan +date: 2021-05-24 +--- + +# 备机处于need repair(WAL)状态问题 + +## 问题现象 + +MogDB备机出现Standby Need repair(WAL)故障。 + +## 原因分析 + +因网络故障、磁盘满等原因造成主备实例连接断开,主备日志不同步,导致数据库在启动时异常。 + +## 处理分析 + +通过`gs_ctl build -D`命令对故障节点进行重建,具体的操作方法请参见MogDB工具参考中的[build参数](../../reference-guide/tool-reference/tools-used-in-the-internal-system/4-gs_ctl.md#build)。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/4-insufficient-memory.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/4-insufficient-memory.md new file mode 100644 index 00000000..880ff99b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/4-insufficient-memory.md @@ -0,0 +1,20 @@ +--- +title: 内存不足问题 +summary: 内存不足问题 +author: Guo Huan +date: 2021-05-24 +--- + +# 内存不足问题 + +## 问题现象 + +客户端或日志里出现错误:memory usage reach the max_dynamic_memory。 + +## 原因分析 + +出现内存不足可能因GUC参数max_process_memory值设置较小相关,该参数限制一个MogDB实例可用最大内存。 + +## 处理分析 + +通过工具gs_guc适当调整max_process_memory参数值。注意需重启实例生效。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/5-service-startup-failure.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/5-service-startup-failure.md new file mode 100644 index 00000000..1f6327ef --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/5-service-startup-failure.md @@ -0,0 +1,91 @@ +--- +title: 服务启动失败 +summary: 服务启动失败 +author: Guo Huan +date: 2021-05-24 +--- + +# 服务启动失败 + +## 问题现象 + +服务启动失败。 + +## 原因分析 + +- 配置参数不合理,数据库因系统资源不足,或者配置参数不满足内部约束,启动失败。 +- 由于部分数据节点状态不正常,导致数据库启动失败。 +- 目录权限不够。例如对/tmp目录、数据库数据目录的权限不足。 +- 配置的端口已经被占用。 +- 开启了系统防火墙导致数据库启动失败。 +- 组成数据库的各台机器之间需要正确建立互信关系,在互信关系出现异常的情况下,数据库将无法启动。 +- 数据库控制文件损坏。 + +## 处理办法 + +- 确认是否由于参数配置不合理导致系统资源不足或不满足内部约束启动失败。 + + - 登录启动失败的节点,检查运行日志确认是否因资源不足启动失败或配置参数不满足内部约束。例如出现Out of memory的错误,或如下错误提示均为资源不足启动失败或配置参数不满足内部约束。 + + ``` + FATAL: hot standby is not possible because max_connections = 10 is a lower setting than on the master server (its value was 100) + ``` + + - 检查GUC参数配置的合理性。例如,shared_buffers、effective_cache_size、bulk_write_ring_size等消耗资源过大的参数;或max_connections等增加后不容易减少的参数。详情请参见[推荐参数设置及新建测试库](../../installation-guide/recommended-parameter-settings.md)。 + +- 确认是否由于实例状态不正常,导致数据库启动失败。通过`gs_om -t status --detail`命令,查询当前数据库各主备机实例的状态。 + + - 如果某一节点上的所有实例都异常,请进行主机替换。 + + - 如果发现某一实例状态为Unknown、Pending和Down的状态,则以数据库用户登录到状态不正常的实例所在节点,查看该实例的日志检查状态异常的原 因。例如: + + ``` + 2014-11-27 14:10:07.022 CST 140720185366288 FATAL: database "mogdb" does not exist 2014-11-27 14:10:07.022 CST 140720185366288 DETAIL: The database subdirectory "base/ 13252" is missing. + ``` + + 如果日志中出现上面这种报错信息,则说明该数据节点的数据目录文件遭到破坏,该实例无法执行正常查询,需要进行替换实例操作。 + +- 目录权限不够处理办法。例如,对/tmp目录、数据库数据目录的权限不足。 + + - 根据错误提示,确认权限不足的目录名称。 + - 使用chmod命令修改目录权限使其满足要求。对于/tmp目录,数据库用户需要具有读写权限。对于数据库数据目录,请参考权限无问题的同类目录进行设置。 + +- 确认是否由于配置的端口已经被占用,导致数据库启动失败。 + + - 登录启动失败的节点,查看实例进程是否存在。 + + - 如果实例进程不存在,则可以通过查看该实例的日志来检查启动异常的原因。例如: + + ``` + 2014-10-17 19:38:23.637 CST 139875904172320 LOG: could not bind IPv4 socket at the 0 time: Address already in use 2014-10-17 19:38:23.637 CST 139875904172320 HINT: Is another postmaster already running on port 40005? If not, wait a few seconds and retry. + ``` + + 如果日志中出现上面这种报错信息,则说明该数据节点的TCP端口已经被占用,该实例无法正常启动。 + + ``` + 2015-06-10 10:01:50 CST 140329975478400 [SCTP MODE] WARNING: (sctp bind) bind(socket=9, [addr:0.0.0.0,port:1024]):Address already in use -- attempt 10/10 2015-06-10 10:01:50 CST 140329975478400 [SCTP MODE] ERROR: (sctp bind) Maximum bind() attempts. Die now... + ``` + + 如果日志中出现上面这种报错信息,则说明该数据节点的SCTP端口已经被占用,该实例无法正常启动。 + +- 通过`sysctl -a`查看net.ipv4.ip_local_port_range,如果该实例配置的端口在系统随机占用端口号的范围内,则可以修改系统随机占用端口号的范围,确保xml文件中所有实例端口号均不在这个范围内。检查某个端口是否被占用的命令如下。 + + ``` + netstat -anop | grep 端口号 + ``` + + 示例如下。 + + ``` + [root@MogDB36 ~]# netstat -anop | grep 15970 + tcp 0 0 127.0.0.1:15970 0.0.0.0:* LISTEN 3920251/mogdb off (0.00/0/0) + tcp6 0 0 ::1:15970 :::* LISTEN 3920251/mogdb off (0.00/0/0) + unix 2 [ ACC ] STREAM LISTENING 197399441 3920251/mogdb /tmp/.s.PGSQL.15970 + unix 3 [ ] STREAM CONNECTED 197461142 3920251/mogdb /tmp/.s.PGSQL.15970 + ``` + +- 确认是否是由于开启了系统防火墙导致数据库启动失败。 + +- 确认是否由于互信关系出现异常,导致数据库无法启动。重新配置实例中各台机器的互信关系解决此问题。 + +- 确认是否由于数据库控制文件如mogdb.state损坏或文件被清空,导致数据库无法启动。若主机控制文件损坏,可触发备机failover,然后通过重建恢复原主机;若备机控制文件损坏,可直接通过重建方式恢复备机。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/6-error-no-space-left-on-device-is-displayed.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/6-error-no-space-left-on-device-is-displayed.md new file mode 100644 index 00000000..a2eeedac --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/6-error-no-space-left-on-device-is-displayed.md @@ -0,0 +1,64 @@ +--- +title: 出现“Error:No space left on device”提示 +summary: 出现“Error:No space left on device”提示 +author: Guo Huan +date: 2021-05-24 +--- + +# 出现“Error:No space left on device”提示 + +## 问题现象 + +在数据库使用过程中,出现如下错误提示。 + +``` +Error:No space left on device +``` + +## 原因分析 + +磁盘空间不足造成此提示信息。 + +## 处理办法 + +- 使用如下命令查看磁盘占用情况。显示信息如下,其中Avail列表示各磁盘可用的空间,Use%列表示已使用的磁盘空间百分比。 + + ``` + [root@openeuler123 mnt]# df -h + Filesystem Size Used Avail Use% Mounted on + devtmpfs 255G 0 255G 0% /dev + tmpfs 255G 35M 255G 1% /dev/shm + tmpfs 255G 57M 255G 1% /run + tmpfs 255G 0 255G 0% /sys/fs/cgroup + /dev/mapper/openeuler-root 196G 8.8G 178G 5% / + tmpfs 255G 1.0M 255G 1% /tmp + /dev/sda2 9.8G 144M 9.2G 2% /boot + /dev/sda1 10G 5.8M 10G 1% /boot/efi + ``` + + 由于业务数据的增长情况不同,对剩余磁盘空间的要求不同。建议如下: + + - 持续观察磁盘空间增长情况,确保剩余空间满足一年以上的增长要求。 + - 数据目录所在磁盘已使用空间>60%则进行空间清理或者扩容。 + +- 使用如下命令查看数据目录大小。 + + ``` + du --max-depth=1 -h /mnt/ + ``` + + 显示如下信息,其中第一列表示目录或文件的大小,第二列是“/mnt/”目录下的所有子目录或者文件。 + + ``` + [root@MogDB36 mnt]# du --max-depth=1 -h /mnt + 83G /mnt/data3 + 71G /mnt/data2 + 365G /mnt/data1 + 518G /mnt + ``` + +- 清理磁盘空间。建议定期将审计日志备份到其他存储设备,推荐的日志保留时长为一个月。pg_log存放数据库各进程的运行日志,运行日志可以帮助数据库管理员定位数据库的问题。如果每日查看错误日志并及时处理错误,则可以删除这些日志。 + +- 清理无用的数据。通过先备份使用频率较低或者一定时间以前的数据至更低成本的存储介质中,然后清理这些已备份的数据来获取更多的磁盘空间。 + +- 如果以上方法无法清理出足够的空间,请对磁盘空间进行扩容。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/7-after-you-run-the-du-command.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/7-after-you-run-the-du-command.md new file mode 100644 index 00000000..14f5207d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/7-after-you-run-the-du-command.md @@ -0,0 +1,32 @@ +--- +title: 在XFS文件系统中,使用du命令查询数据文件大小大于文件实际大小 +summary: 在XFS文件系统中,使用du命令查询数据文件大小大于文件实际大小 +author: Guo Huan +date: 2021-05-24 +--- + +# 在XFS文件系统中,使用du命令查询数据文件大小大于文件实际大小 + +## 问题现象 + +在数据库使用过程中,通过如下du命令查询数据文件大小,查询结果大于文件实际的大小。 + +``` +du -sh file +``` + +## 原因分析 + +XFS文件系统有预分配机制,预分配的大小由参数allocsize确定。du命令显示的文件大小包括该预分配的磁盘空间。 + +## 处理办法 + +- 将XFS文件系统挂载选项allocsize设置为默认值(64KB)减缓该问题。 + +- 使用du命令时,增加--apparent-size选项,查看实际文件的大小。 + + ```bash + du -sh file --apparent-size + ``` + +- XFS文件系统有回收预分配空间的机制,文件系统可以通过回收文件预分配的空间,使du命令显示为实际文件的大小。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/8-file-is-damaged-in-the-xfs-file-system.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/8-file-is-damaged-in-the-xfs-file-system.md new file mode 100644 index 00000000..fa9547a2 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/8-file-is-damaged-in-the-xfs-file-system.md @@ -0,0 +1,22 @@ +--- +title: 在XFS文件系统中,出现文件损坏 +summary: 在XFS文件系统中,出现文件损坏 +author: Guo Huan +date: 2021-05-24 +--- + +# 在XFS文件系统中,出现文件损坏 + +## 问题现象 + +在数据库使用过程中,有极小的概率出现XFS文件系统的报错(Input/Output error, structure needs cleaning)。 + +## 原因分析 + +此为XFS文件系统问题。 + +## 处理办法 + +首先尝试umount/mount对应文件系统,重试看是否可以规避此问题。 + +如果问题重现,则需要参考文件系统相应的文档请系统管理员对文件系统进行修复,例如xfs_repair。文件系统成功修复后,请使用`gs_ctl build`命令来修复文件受损的数据节点。 diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/9-primary-node-is-hung-in-demoting.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/9-primary-node-is-hung-in-demoting.md new file mode 100644 index 00000000..b02d1697 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-cases/9-primary-node-is-hung-in-demoting.md @@ -0,0 +1,24 @@ +--- +title: switchover操作时,主机降备卡住 +summary: switchover操作时,主机降备卡住 +author: Guo Huan +date: 2021-05-24 +--- + +# switchover操作时,主机降备卡住 + +## 问题现象 + +一主多备模式下,系统资源不足时,发生switchover,出现主机降备时卡住。 + +## 原因分析 + +当系统资源不足时,无法创建第三方管理线程,导致其管理的子线程无法退出,出现主机降备时卡住。 + +## 处理办法 + +需要执行以下命令终止主机进程,使备机正常升主。确定为上述场景时执行以下操作,不是上述场景时请勿按照本方法执行。 + +```bash + kill -9 PID +``` diff --git a/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-methods.md b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-methods.md new file mode 100644 index 00000000..4859e92d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/common-faults-and-identification/common-fault-locating-methods.md @@ -0,0 +1,283 @@ +--- +title: 常见故障定位手段 +summary: 常见故障定位手段 +author: Guo Huan +date: 2021-05-24 +--- + +# 常见故障定位手段 + +## 操作系统故障定位手段 + +查询状态时,显示一个节点上所有实例都不正常时,可能是操作系统发生了故障。 + +可以通过如下方法确定操作系统是否存在问题: + +- 通过SSH或者其它远程登录工具登录该节点。如果连接失败,请尝试通过ping发包检查网络状态。 + + - 如果ping操作没有回复,则表明这台机器可能存在网络连接故障、处于宕机状态或者正处于重启状态。 + + 如果操作系统内核发生panic引起系统崩溃,系统重新启动时间较慢,需经过较长时间(大约20分钟)才能重启。建议每5分钟尝试连接一次,20分钟后不能连接成功,则表明这台机器已宕机或网络连接有问题,需要管理员到现场进行检查处理。 + + - 如果网络可以ping通,但在SSH登入时卡住或登入后不能执行任何命令,通常是由系资源不足(如CPU或IO资源过载)引起的机器不响应外部连接。建议重试几次。如果5分钟内仍不能成功,需要管理员到现场进行检查处理。 + +- 可以远程登录节点,但在执行操作时,响应缓慢,需要检查系统运行情况后,进行进一步处理。例如,收集系统信息、确定系统版本、硬件、参数设置及登录用户情况。下面列出一些常用命令供参考。 + + - `who`命令查看当前在线用户。 + + ```bash + [root@MogDB36 ~]# who + root pts/0 2020-11-07 16:32 (10.70.223.238) + wyc pts/1 2020-11-10 09:54 (10.70.223.222) + root pts/2 2020-10-10 14:20 (10.70.223.238) + root pts/4 2020-10-09 10:14 (10.70.223.233) + root pts/5 2020-10-09 10:14 (10.70.223.233) + root pts/7 2020-10-31 17:03 (10.70.223.222) + root pts/9 2020-10-20 10:03 (10.70.220.85) + ``` + + - `cat /etc/openEuler-release`和`uname -a`命令检查系统的版本和内核信息。 + + ```bash + [root@MogDB36 ~]# cat /etc/openEuler-release + openEuler release 20.03 (LTS) + [root@MogDB36 ~]# uname -a + Linux MogDB36 4.19.90-2003.4.0.0036.oe1.aarch64 #1 SMP Mon Mar 23 19:06:43 UTC 2020 aarch64 aarch64 aarch64 GNU/Linux + [root@MogDB36 ~]# + ``` + + - `sysctl -a`命令(需要root用户执行)和`cat /etc/sysctl.conf`命令获得系统参数信息。 + + - `cat /proc/cpuinfo`和`cat /proc/meminfo`获得CPU和内存信息。 + + ```bash + [root@MogDB36 ~]# cat /proc/cpuinfo + processor : 0 + BogoMIPS : 200.00 + Features : fp asimd evtstrm aes pmull sha1 sha2 crc32 atomics fphp asimdhp cpuid asimdrdm jscvt fcma dcpop asimddp asimdfhm + CPU implementer : 0x48 + CPU architecture: 8 + CPU variant : 0x1 + CPU part : 0xd01 + CPU revision : 0 + [root@MogDB36 ~]# cat /proc/meminfo + MemTotal: 534622272 kB + MemFree: 253322816 kB + MemAvailable: 369537344 kB + Buffers: 2429504 kB + Cached: 253063168 kB + SwapCached: 0 kB + Active: 88570624 kB + Inactive: 171801920 kB + Active(anon): 4914880 kB + Inactive(anon): 67011456 kB + Active(file): 83655744 kB + Inactive(file): 104790464 kB + ``` + + - `top -H”命令查看CPU的使用情况,确定是否因为某个进程导致CPU使用率过高。如果存在这种情况,通过gdb或gstack打印该程序堆栈,观察是否该程序处于死循环逻辑。 + + - `iostat -x 1 3”命令查看IO的使用情况,确定是否当前磁盘的IO处于饱和状态。查看当前运行的执行作业情况,决定是否对占用较多IO的执行作业进行处理。 + + - `vmstat 1 3`命令查看当前系统中内存的消耗情况,结合`top`命令获得消耗内存较多的进程,处于超出预期的状态。 + + - 以root用户查看操作系统日志信息(/var/log/messages)或dmseg信息,检查操作系统是否发生过异常错误。 + + - 操作系统的watchdog是为了保证OS系统正常运行,或者从死循环,死锁等状态退出的一种机制,如果watchdog超时(一般默认值为60s),系统将会复位。 + +## 网络故障定位手段 + +在数据库正常工作的情况下,网络层对上层用户是透明的,但数据库在长期运行时,可能会由于各种原因导致出现网络异常或错误。常见的因网络故障引发的异常有: + +- 数据库启动失败,报网络错误。 +- 状态异常,如:节点上所有的实例都是UnKnown或者所有主机都切换为备机。 +- 网络连接建立失败。 +- 对数据库执行SQL操作时,报网络异常中断的错误。 +- 连接数据库或执行查询时发生进程停止响应。数据库出现了网络故障后,主要通过使用Linux系统提供的网络相关命令工具(ping、ifconfig、netstat、lsof等),进程堆栈查看工具(gdb、gstack),结合数据库的日志信息,进行分析定位。本节通过举例介绍常见的网络问题,并进行基本的分析定位。 + +常见故障问题如下: + +- 启动失败,报网络错误 + + **问题现象1**:日志中存在如下错误信息。可能是端口被其他进程侦听。 + + ```bash + LOG: could not bind socket at the 10 time, is another postmaster already running on port 54000? + ``` + + **处理办法**:执行如下命令查看侦听该端口的进程。端口号请根据实际端口号替换。 + + ```bash + [root@MogDB36 ~]# netstat -anop | grep 15970 + tcp 0 0 127.0.0.1:15970 0.0.0.0:* LISTEN 3920251/mogdb off (0.00/0/0) + tcp6 0 0 ::1:15970 :::* LISTEN 3920251/mogdb off (0.00/0/0) + unix 2 [ ACC ] STREAM LISTENING 197399441 3920251/mogdb /tmp/.s.PGSQL.15970 + unix 3 [ ] STREAM CONNECTED 197461142 3920251/mogdb /tmp/.s.PGSQL.15970 + + ``` + + 根据查询结果,强行停止正在占用端口的进程或者更改数据库侦听端口。 + + **问题现象2**:使用`gs_om -t status --detail`查询状态,如果显示主备间连接未建立。 + + **处理办法**:在openEuler操作系统下,使用`systemctl status firewalld.service`命令,查看节点上是否 开启了防火墙。如果开启,使用`systemctl stop firewalld.service`关闭防火墙。 + + ```bash + [root@MogDB36 mnt]# systemctl status firewalld.service + firewalld.service - firewalld - dynamic firewall daemon + Loaded: loaded (/usr/lib/systemd/system/firewalld.service; disabled; vendor preset: enabled) + Active: inactive (dead) + Docs: man:firewalld(1) + ``` + + 操作系统不同,命令可能不同,使用对应操作系统命令查看修改。 + +- 数据库状态异常 + + **问题现象**:某一节点上出现如下问题: + + - 所有实例都是UnKnown。 + - 所有主实例都切换成了备实例。 + - 查询中出现大量Connection reset by peer,Connection timed out等报错信息。 + + **处理办法** + + - 如果ssh不能连接故障机器,在其他机器上使用Ping命令向该机器发数据包。如果可以Ping通,说明可能是该机器上的资源(内存、CPU、磁盘)耗尽导致不能建立连接。 + + - 如果ssh可以连接该机器,尝试执行查询,并每隔1s执行`/sbin/ifconfig eth?`(?代表数字,表示第几个网卡)命令,查看如下信息中的dropped及errors值的变化情况, 如果增长迅速,可能是网卡或网卡驱动故障。 + + ```bash + [root@MogDB36 ~]# ifconfig enp125s0f0 + enp125s0f0: flags=4163 mtu 1500 + inet 10.90.56.36 netmask 255.255.255.0 broadcast 10.90.56.255 + inet6 fe80::7be7:8038:f3dc:f916 prefixlen 64 scopeid 0x20 + ether 44:67:47:7d:e6:84 txqueuelen 1000 (Ethernet) + RX packets 129344246 bytes 228050833914 (212.3 GiB) + RX errors 0 dropped 647228 overruns 0 frame 0 + TX packets 96689431 bytes 97279775245 (90.5 GiB) + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 + ``` + + - 检查如下参数设置是否正确。 + + ```bash + net.ipv4.tcp_retries1 = 3 + net.ipv4.tcp_retries2 = 15 + ``` + +- 网络连接建立失败 + + **问题现象1**:节点连接其他节点失败,日志中报出“Connection refused”错误。 + + **处理办法**: + + - 查看端口是否配置错误,导致连接时使用的端口并非对方侦听的端口。查看报错节点配置文件postgresql.conf记录端口号与对方侦听的端口就号是否一致。 + - 查看对方端口侦听是否正常(可以使用`netstat -anp`命令)。 + - 查看对方进程是否存在。 + + **问题现象2**:对数据库执行SQL操作时,获取连接描述符失败,报错如下。 + + ```sql + WARNING: 29483313: incomplete message from client:4905,9 + WARNING: 29483313: failed to receive connDefs at the time:1. + ERROR: 29483313: failed to get pooled connections + ``` + + 在日志中,找到上面的错误,并向上查看一段日志内容,可以看到详细的错误信息,常见的错误如下所示,主要是由于主备信息不正确导致。 + + ```sql + FATAL: dn_6001_6002: can not accept connection in pending mode. + FATAL: dn_6001_6002: the database system is starting up + FATAL: dn_6009_6010: can not accept connection in standby mode. + ``` + + **处理办法:** + + - 使用`gs_om -t status --detail`查询状态,确认是否发生过主备切换。重置实例状态。 + - 此外,需要查看连接失败的节点是否发生了core或者重启。通过om日志可以查看到是否发生了重启。 + +- 对数据库执行SQL操作时,报网络异常中断的错误 + + **问题现象1**:查询执行失败,报错信息如下。 + + ```sql + ERROR: dn_6065_6066: Failed to read response from Datanodes. Detail: Connection reset by peer. Local: dn_6065_6066 Remote: dn_6023_6024 + ERROR: Failed to read response from Datanodes Detail: Remote close socket unexpectedly + ERROR: dn_6155_6156: dn_6151_6152: Failed to read vector response from Datanodes + ``` + + 连接建立失败,报错信息如下。 + + ```sql + ERROR: Distribute Query unable to connect 10.145.120.79:14600 [Detail:stream connect connect() fail: Connection timed out + ERROR: Distribute Query unable to connect 10.144.192.214:12600 [Detail:receive accept response fail: Connection timed out + ``` + + **处理办法**: + + 1. 使用gs_check检查网络配置是否符合标准。详细参考《参考指南》中“工具参考 > 服务端工具 > [gs_check](../reference-guide/tool-reference/server-tools/1-gs_check.md)”章节中对network的检查。 + 2. 查看是否有进程发生core或重启,以及主备切换。 + 3. 如果不存在上述问题,可以联系网络技术人员做具体分析。 + +## 磁盘故障定位手段 + +常见的磁盘故障是磁盘空间不足、磁盘出现坏块、磁盘未挂载等。 部分磁盘故障会导致文件系统损坏,例如磁盘未挂载,数据库管理自动定期执行磁盘检测时会识别故障并将实例停止,查看数据库状态时对应实例状态异常;部分磁盘故障不会导致文件系统损坏,例如磁盘空间不足,数据库管理无法检测到,服务进程访问到故障磁盘会异常退出,例如数据库无法启动、checksum校验不对、页面读写失败、页面校验错误等。 + +- 对于会导致文件系统损坏的故障,查看状态会显示对应实例状态持续为Unknown,定位方法如下: + + - 查看日志,日志中会有类似“data path disc writable test failed”异常,说明文件系统已损坏。 + + - 文件系统损坏可能是磁盘未挂载,通过`ls -l`可以看到该磁盘对应的目录权限异常,如下: + + - 也可能是磁盘出现坏块,然后操作系统将文件系统保护起来,拒绝读写,可以使 用磁盘坏块检查工具如badblocks检查磁盘是否有坏块,如下 + + ```bash + [root@openeuler123 mnt]# badblocks /dev/sdb1 -s -v + Checking blocks 0 to 2147482623 + Checking for bad blocks (read-only test): done + Pass completed, 0 bad blocks found. (0/0/0 errors) + ``` + +- 对于不会导致文件系统损坏的故障,服务进程访问到故障磁盘会异常退出,定位方法如下。 + + 查看日志。日志中会有文件读写错误,例如“No space left on device”、“invalid page header n block 122838 of relation base/16385/152715”。文件读写错误可能是磁盘空间不足,通过`df -h`可以看到磁盘空间已达100%,如下。 + + ``` + [root@openeuler123 mnt]# df -h + Filesystem Size Used Avail Use% Mounted on + devtmpfs 255G 0 255G 0% /dev + tmpfs 255G 35M 255G 1% /dev/shm + tmpfs 255G 57M 255G 1% /run + tmpfs 255G 0 255G 0% /sys/fs/cgroup + /dev/mapper/openeuler-root 196G 8.8G 178G 5% / + tmpfs 255G 1.0M 255G 1% /tmp + /dev/sda2 9.8G 144M 9.2G 2% /boot + /dev/sda1 10G 5.8M 10G 1% /boot/efi + /dev/mapper/openeuler-home 1.5T 69G 1.4T 5% /home + tmpfs 51G 0 51G 0% /run/user/0 + tmpfs 51G 0 51G 0% /run/user/1004 + /dev/sdb1 2.0T 169G 1.9T 9% /data + ``` + +## 数据库故障定位手段 + +- 日志。数据库日志记录了数据库服务端启动、运行或停止时出现的问题,当数据库在启动、运行或停止的过程中出现问题时,数据库用户可以通过运行日志快速分析问题的产生原因,并根据不同的原因采取相应的处理方法,尽可能地解决问题。 + +- 视图。数据库提供了许多视图,用于展示数据库的内部状态,在定位故障时,经常使用的视图如下: + + - pg_stat_activity,用于查询当前实例上各个session的状态。 + - pg_thread_wait_status,用于查询该实例上各个线程的等待事件。 + - pg_locks,用于查询当前实例上的锁状态。 + +- CORE文件。数据库相关进程在运行过程中可能会因为各种意外情况导致数据库崩溃(Coredump),而崩溃时产生的core文件对于迅速定位程序崩溃的原因及位置非常重要。如果进程运行时出现Coredump现象,建议立即收集core文件便于分析、定位故障。 + + - 对性能有一定的影响,尤其是进程频繁异常时对性能的影响更大。 + + - core文件会占用磁盘空间。因此,当检查到core文件产生后,应及时解决以避免对操作系统带来更严重的影响。操作系统自带core dump机制。开启后,系统中所有出现Coredump问题时都会生成core文件,对操作系统带来性能和磁盘占用的影响 + + - 设置core文件生成路径。修改/proc/sys/kernel/core_pattern内容。 + + ```bash + [root@openeuler123 mnt]# cat /proc/sys/kernel/core_pattern + /data/jenkins/workspace/MogDBInstall/dbinstall/cluster/corefile/core-%e-%p-%t + ``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/1-1-stored-procedure.md b/product/zh/docs-mogdb/v3.1/developer-guide/1-1-stored-procedure.md new file mode 100644 index 00000000..597ee1f6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/1-1-stored-procedure.md @@ -0,0 +1,16 @@ +--- +title: 存储过程 +summary: 存储过程 +author: Guo Huan +date: 2021-03-04 +--- + +# 存储过程 + +商业规则和业务逻辑可以通过程序存储在MogDB中,这个程序就是存储过程。 + +存储过程是SQL和PL/pgSQL的组合。存储过程使执行商业规则的代码可以从应用程序中移动到数据库。从而,代码存储一次能够被多个程序使用。 + +存储过程的创建及调用办法请参考[CREATE PROCEDURE](../reference-guide/sql-syntax/CREATE-PROCEDURE.md)。 + +[用户自定义函数](user-defined-functions.md)一节所提到的PL/pgSQL语言创建的函数与存储过程的应用方法相通。具体介绍请参看[PL/pgSQL-SQL过程语言](../developer-guide/plpgsql/1-1-plpgsql-overview.md)章节,除非特别声明,否则其中内容通用于存储过程和用户自定义函数。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/1-introduction-to-autonomous-transaction.md b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/1-introduction-to-autonomous-transaction.md new file mode 100644 index 00000000..7c4574e8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/1-introduction-to-autonomous-transaction.md @@ -0,0 +1,12 @@ +--- +title: 介绍 +summary: 介绍 +author: Zhang Cuiping +date: 2021-05-10 +--- + +# 介绍 + +自治事务(Autonomous Transaction),在主事务执行过程中新启的独立的事务。自治事务的提交和回滚不会影响主事务已提交的数据,同时自治事务也不受主事务影响。 + +自治事务在存储过程、函数和匿名块中定义,用PRAGMA AUTONOMOUS_TRANSACTION关键字来声明。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/2-function-supporting-autonomous-transaction.md b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/2-function-supporting-autonomous-transaction.md new file mode 100644 index 00000000..e045b125 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/2-function-supporting-autonomous-transaction.md @@ -0,0 +1,56 @@ +--- +title: 用户自定义函数支持自治事务 +summary: 用户自定义函数支持自治事务 +author: Zhang Cuiping +date: 2021-05-10 +--- + +# 用户自定义函数支持自治事务 + +自治事务可以在函数中定义,标识符为PRAGMA AUTONOMOUS_TRANSACTION,执行的函数块中使用包含start transaction和commit/rollback的sql,其余语法与[CREATE FUNCTION](../../reference-guide/sql-syntax/CREATE-FUNCTION.md)创建函数语法类似,一个简单的用例如下: + +```sql +--建表 +MogDB=# create table t2(a int, b int); +MogDB=# insert into t2 values(1,2); +MogDB=# select * from t2; +a | b +---+--- +1 | 2 +(1 row) + +--创建包含自治事务的存储过程 +CREATE OR REPLACE PROCEDURE autonomous_4(a int, b int) AS +DECLARE + num3 int := a; + num4 int := b; + PRAGMA AUTONOMOUS_TRANSACTION; +BEGIN + insert into t2 values(num3, num4); + +END; +/ +--创建调用自治事务存储过程的普通存储过程 +CREATE OR REPLACE PROCEDURE autonomous_5(a int, b int) AS +DECLARE +BEGIN + + insert into t2 values(666, 666); + autonomous_4(a,b); + rollback; +END; +/ +--调用普通存储过程 +MogDB=# select autonomous_5(11,22); +autonomous_5 +(1 row) +--查看表结果 +MogDB=# select * from t2 order by a; +a | b +----+---- +1 | 2 +11 | 22 +(2 rows) +``` + +上述例子,最后在回滚的事务块中执行包含自治事务的函数,直接说明了自治事务的特性,即主事务的回滚,不会影响自治事务已经提交的内容。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/3-stored-procedure-supporting-autonomous-transaction.md b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/3-stored-procedure-supporting-autonomous-transaction.md new file mode 100644 index 00000000..82c0878c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/3-stored-procedure-supporting-autonomous-transaction.md @@ -0,0 +1,45 @@ +--- +title: 存储过程支持自治事务 +summary: 存储过程支持自治事务 +author: Zhang Cuiping +date: 2021-05-10 +--- + +# 存储过程支持自治事务 + +自治事务可以在存储过程中定义,标识符为PRAGMA AUTONOMOUS_TRANSACTION,其余语法与创建存储过程语法相同,示例如下。 + +```sql +--建表 +create table t2(a int, b int); +insert into t2 values(1,2); +select * from t2; + +--创建包含自治事务的存储过程 +CREATE OR REPLACE PROCEDURE autonomous_4(a int, b int) AS +DECLARE + num3 int := a; + num4 int := b; + PRAGMA AUTONOMOUS_TRANSACTION; +BEGIN + insert into t2 values(num3, num4); + dbe_output.print_line('just use call.'); +END; +/ +--创建调用自治事务存储过程的普通存储过程 +CREATE OR REPLACE PROCEDURE autonomous_5(a int, b int) AS +DECLARE +BEGIN + dbe_output.print_line('just no use call.'); + insert into t2 values(666, 666); + autonomous_4(a,b); + rollback; +END; +/ +--调用普通存储过程 +select autonomous_5(11,22); +--查看表结果 +select * from t2 order by a; +``` + +上述例子,最后在回滚的事务块中执行包含自治事务的存储过程,直接说明了自治事务的特性,即主事务的回滚,不会影响自治事务已经提交的内容。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/4-restrictions.md b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/4-restrictions.md new file mode 100644 index 00000000..527bdd83 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/4-restrictions.md @@ -0,0 +1,150 @@ +--- +title: 规格约束 +summary: 规格约束 +author: Zhang Cuiping +date: 2021-05-10 +--- + +# 规格约束 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** +> +> - 自治事务执行时,将会在后台启动自治事务session,我们可以通过max_concurrent_autonomous_transactions设置自治事务执行的最大并行数量,该参数取值范围为0~1024,默认值为10。 +> - 当max_concurrent_autonomous_transactions参数设置为0时,自治事务将无法执行。 +> - 自治事务新启session后,将使用默认session参数,不共享主session下对象(包括session级别变量,本地临时变量,全局临时表的数据等)。 + +- 触发器函数不支持自治事务。 + + ```sql + CREATE TABLE test_trigger_des_tbl(id1 INT, id2 INT, id3 INT); + + CREATE OR REPLACE FUNCTION tri_insert_func() RETURNS TRIGGER AS + $$ + DECLARE + PRAGMA AUTONOMOUS_TRANSACTION; + BEGIN + INSERT INTO test_trigger_des_tbl VALUES(NEW.id1, NEW.id2, NEW.id3); + RETURN NEW; + END + $$ LANGUAGE PLPGSQL; + ``` + +- 自治事务不支持非顶层匿名块调用(仅支持顶层自治事务,包括存储过程、函数、匿名块)。 + +- 自治事务不支持ref_cursor参数传递。 + + ```sql + create table sections(section_ID int); + insert into sections values(1); + insert into sections values(1); + insert into sections values(1); + insert into sections values(1); + + CREATE OR REPLACE function proc_sys_ref() + return SYS_REFCURSOR + IS + declare + PRAGMA AUTONOMOUS_TRANSACTION; + C1 SYS_REFCURSOR; + BEGIN + OPEN C1 FOR SELECT section_ID FROM sections ORDER BY section_ID; + return C1; + END; + / + + CREATE OR REPLACE PROCEDURE proc_sys_call() AS + DECLARE + C1 SYS_REFCURSOR; + TEMP NUMBER(4); + BEGIN + c1 = proc_sys_ref(); + if c1%isopen then + raise notice '%','ok'; + end if; + + LOOP + FETCH C1 INTO TEMP; + raise notice '%',C1%ROWCOUNT; + EXIT WHEN C1%NOTFOUND; + END LOOP; + END; + / + + select proc_sys_call(); + + CREATE OR REPLACE function proc_sys_ref(OUT C2 SYS_REFCURSOR, OUT a int) + return SYS_REFCURSOR + IS + declare + PRAGMA AUTONOMOUS_TRANSACTION; + C1 SYS_REFCURSOR; + BEGIN + OPEN C1 FOR SELECT section_ID FROM sections ORDER BY section_ID; + return C1; + END; + / + + CREATE OR REPLACE PROCEDURE proc_sys_call() AS + DECLARE + C1 SYS_REFCURSOR; + TEMP NUMBER(4); + a int; + BEGIN + OPEN C1 FOR SELECT section_ID FROM sections ORDER BY section_ID; + c1 = proc_sys_ref(C1,a); + if c1%isopen then + raise notice '%','ok'; + end if; + + LOOP + FETCH C1 INTO TEMP; + raise notice '%',C1%ROWCOUNT; + EXIT WHEN C1%NOTFOUND; + END LOOP; + END; + / + + select proc_sys_call(); + ``` + +- 自治事务函数不支持返回非out形式的record类型。 + +- 不支持修改自治事务的隔离级别。 + +- 不支持自治事务返回集合类型(setof)。 + + ```sql + create table test_in (id int,a date); + create table test_main (id int,a date); + insert into test_main values (1111,'2021-01-01'),(2222,'2021-02-02'); + truncate test_in,test_main; + CREATE OR REPLACE FUNCTION autonomous_f_022(num1 int) RETURNS SETOF test_in + LANGUAGE plpgsql AS $$ + DECLARE + count int :=3; + test_row test_in%ROWTYPE; + PRAGMA AUTONOMOUS_TRANSACTION; + BEGIN + while true + loop + if count=3 then + null; + else + if count=2 then + insert into test_main values (count,'2021-03-03'); + goto pos1; + end if; + end if; + count=count-1; + end loop; + insert into test_main values (1000,'2021-04-04'); + <> + for test_row in select * from test_main + loop + return next test_row; + end loop; + return; + END; + $$ + ; + ``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/anonymous-block-supporting-autonomous-transaction.md b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/anonymous-block-supporting-autonomous-transaction.md new file mode 100644 index 00000000..6dc98603 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/autonomous-transaction/anonymous-block-supporting-autonomous-transaction.md @@ -0,0 +1,36 @@ +--- +title: 匿名块支持自治事务 +summary: 匿名块支持自治事务 +author: Guo Huan +date: 2021-10-15 +--- + +# 匿名块支持自治事务 + +自治事务可以在匿名块中定义,标识符为PRAGMA AUTONOMOUS_TRANSACTION,其余语法与创建匿名块语法相同,示例如下。 + +```sql +MogDB=# create table t1(a int ,b text); +CREATE TABLE + +START TRANSACTION; +DECLARE + PRAGMA AUTONOMOUS_TRANSACTION; +BEGIN + + insert into t1 values(1,'you are so cute,will commit!'); +END; +/ +MogDB=# insert into t1 values(1,'you will rollback!'); +INSERT 0 1 +MogDB=# rollback; +ROLLBACK + +MogDB=# select * from t1; +a | b +---+------------------------------ +1 | you are so cute,will commit! +(1 row) +``` + +上述例子,最后在回滚的事务块前执行包含自治事务的匿名块,也能直接说明了自治事务的特性,即主事务的回滚,不会影响自治事务已经提交的内容。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/1-development-specifications.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/1-development-specifications.md new file mode 100644 index 00000000..13a749da --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/1-development-specifications.md @@ -0,0 +1,753 @@ +--- +title: 开发规范 +summary: 开发规范 +author: Guo Huan +date: 2021-04-27 +--- + +# 开发规范 + +如果用户在APP的开发中,使用了连接池机制,那么需要遵循如下规范: + +- 如果在连接中设置了GUC参数,那么在将连接归还连接池之前,必须使用"SET SESSION AUTHORIZATION DEFAULT;RESET ALL;"将连接的状态清空。 +- 如果使用了临时表,那么在将连接归还连接池之前,必须将临时表删除。 + +否则,连接池里面的连接就是有状态的,会对用户后续使用连接池进行操作的正确性带来影响。 + +兼容性原则: + +新驱动前向兼容数据库,若需使用驱动与数据库同步增加的新特性,必须升级数据库。 + +## 概述 + +### 简介 + +尽管ISO针对SQL已经发布SQL-92、SQL:1999、SQL:2006等标准,但由于不同数据库自身的特性,使得同样功能在各自产品的实现上不尽相同,这也使得相关的语法规则各有千秋。因此,在制定具体开发规范的时候,需要针对不同数据库来编写相应的规范。 + +本规范强调实用性、可操作性,根据开发人员在编码过程中常见的问题和易犯的错误,对代码编写的各方面均进行了详细明确的规范和约束。主要包括下列内容: + +- 命名规范 +- 设计规范 +- 语法规范 +- 优化相关 +- PG兼容性 + +除此之外,对规范的每条细则均给出具体的范例。 + +### 适用范围 + +本规范适用于MogDB 1.0.0及以上版本。 + +## 命名规范 + +### 对象命名统一规范 + +数据库对象,如database、schema、table、column、view、index、constraint、sequence、function、trigger等命名统一标准如下: + +- 长度不能超过63个字符 + +- 命名尽量采用富有意义英文词汇 + +- 建议使用小写字母、数字、下划线的组合 + +- 建议不使用双引号即"包围,除非必须包含大写字母或空格等特殊字符 + +- 不建议以PG、GS开头(避免与系统DB object混淆),不建议以数字开头 + +- 禁止使用[保留字](../../reference-guide/sql-reference/2-keywords.md),保留关键字参考官方文档 + +- table能包含的column数目,根据字段类型的不同,数目在250到1600之间 + +### 临时及备份对象命名 + +- 临时或备份的数据库对象名,如table,建议添加日期,如`dba.trade_record_1970_01_01`(其中dba 为DBA专用schema,trade_record为表名,1970_01_01为备份日期)。 + +### 表空间命名 + +- 数据库的用户表空间用`ts_<表空间名>`来表现,其中,表空间名分为: + 1. 数据空间:对于用户的缺省表空间,用`default`来表现。对于其他的表空间,根据寄存在表空间上的表的类别来表现。如放代码的表,用`code`来表现。放客户资料的表,用`customer`来表现。尽量用一个表空间来寄存该类的表。如果某表特殊大,可考虑单独使用一个表空间。 + 2. 索引空间:在相应的数据表空间的名字前加idx_。如对用户缺省表空间的索引空间,用`ts_idx_default`来表现。对代码表的索引表空间,用`ts_idx_code`来表现。 + +### 索引命名 + +- Index对象命名规则为:`表名_列名_idx`,如`student_name_idx`,该索引命名方式为MogDB数据库在创建索引时没有明确指定索引名称时的默认命名方式。 + + 因此建议创建索引时,不显式给出index name,使用DBMS默认值。 + +```sql +create unique index on departments(department_id); +CREATE INDEX + \di ++----------+-------------------------------+--------+---------+ +| Schema | Name | Type | Owner | +|----------+-------------------------------+--------+---------| +| mogdb | departments_department_id_idx | index | mogdb | ++----------+-------------------------------+--------+---------+ +SELECT 1 +``` + +### 变量命名 + +- 命名应该使用英文单词,避免使用拼音,特别不应该使用拼音简写。命名不允许使用中文或者特殊字符。 + +- 如果不涉及复杂运算,一律用number定义计数等简单应用。 + +### 分区表命名 + +- 分区表的表名遵循普通表的正常命名规则。 + +- 按时间范围分区(每月一个分区),分区名字为`PART_YYYYMM`。 + + 举例: PART_201901、PART_201902 + +### 函数命名 + +- 名称应与其实际功能保持一致。导致发生某动作应以动词为前缀命令。 + + 示例:以下命名符合规范: + + ``` + func_addgroups(增加多个群组) + func_addgroup(增加一个群组) + ``` + +## 设计规范 + +### database设计 + +- 建议以业务功能来命名数据库,简单直观。 + +- 业务数据库推荐以兼容PG的方式来创建。 + +- 数据库编码推荐用utf8。 + +### tablespace设计 + +- 频繁使用的表和索引单独存放在一个表空间,此表空间应在性能好的磁盘上创建。 + +- 以历史数据为主,或活跃度较低的表和索引可以存放在磁盘性能较差的表空间。 + +- 表和索引可以单独存放在不同的表空间。 + +- 表空间也可以按数据库分、按schema分或按业务功能来分。 + +- 每个database/schema对应一个表空间和一个相应索引表空间。 + +### schema设计 + +- 在一个数据库下执行创建用户时,默认会在该数据库下创建一个同名schema。 +- 不建议在默认public schema下创建数据库对象。 +- 创建一个与用户名不同的schema给业务使用。 + +### table设计 + +- 设计表结构时,应该规划好,避免经常添加字段,或者修改字段类型或长度。 + +- 必须为表添加注释信息,表名与注释信息相匹配。 + +- 禁止使用unlogged/ temp/temporary关键字创建业务表。 + +- 作为表间连接关系的字段,数据类型必须保持严格一致,避免索引无法正常使用。 + +- 禁止使用VARCHAR或其他字符类型来存储日期值,如果使用,则不能在此字段上做运算,需要在数据规范中严格定义。 + +- 对于频繁更新的astore表,建议建表时指定表的fillfactor=85,给HOT预留空间。 + +- 频繁更新使用的表应该单独放在存储性能好的表空间。 + +- 数据量超过亿级或占用磁盘超过10GB的表,建议考虑分区。 + +- 表结构中字段定义的数据类型与应用程序中的定义保持一致,表之间字段校对规则一致,避免报错或无法使用索引的情况发生。 + + > 说明:比如A表user_id字段数据类型定义为varchar,但是SQL语句查询为`where user_id=1234;` + +### partition table设计 + +- 分区表的个数不建议超过1000个。 + +- 分区表可以按使用频度选择不同的表空间。 + +- 主键或唯一索引必须要包含分区键。 + +- 对于数据量比较大的表,根据表数据的属性进行分区,以得到较好的性能。 + +- 普通表若要转成分区表,需要新建分区表,然后把普通表中的数据导入到新建的分区表中。因此在初始设计表时,请根据业务提前规划是否使用分区表。 + +- 建议有定期历史数据删除需求的业务,表按时间分区,删除时不要使用DELETE操作,而是DROP或者TRUNCATE对应的表。 + +- 在分区表中不建议使用全局索引,因为做分区维护操作时可能会导致全局索引失效,造成难以维护。 + +#### 分区表的使用 + +按照以下方式对范围分区表进行操作。 + +- 创建表空间 + +```sql +MogDB=# CREATE TABLESPACE example1 RELATIVE LOCATION 'tablespace1/tablespace_1'; +MogDB=# CREATE TABLESPACE example2 RELATIVE LOCATION 'tablespace2/tablespace_2'; +MogDB=# CREATE TABLESPACE example3 RELATIVE LOCATION 'tablespace3/tablespace_3'; +MogDB=# CREATE TABLESPACE example4 RELATIVE LOCATION 'tablespace4/tablespace_4'; +``` + +当结果显示为如下信息,则表示创建成功。 + +```sql +CREATE TABLESPACE +``` + +- 创建分区表 + +```sql +MogDB=# CREATE TABLE mogdb_usr.customer_address +( + ca_address_sk integer NOT NULL , + ca_address_id character(16) NOT NULL , + ca_street_number character(10) , + ca_street_name character varying(60) , + ca_street_type character(15) , + ca_suite_number character(10) , + ca_city character varying(60) , + ca_county character varying(30) , + ca_state character(2) , + ca_zip character(10) , + ca_country character varying(20) , + ca_gmt_offset numeric(5,2) , + ca_location_type character(20) +) +TABLESPACE example1 + +PARTITION BY RANGE (ca_address_sk) +( + PARTITION P1 VALUES LESS THAN(5000), + PARTITION P2 VALUES LESS THAN(10000), + PARTITION P3 VALUES LESS THAN(15000), + PARTITION P4 VALUES LESS THAN(20000), + PARTITION P5 VALUES LESS THAN(25000), + PARTITION P6 VALUES LESS THAN(30000), + PARTITION P7 VALUES LESS THAN(40000), + PARTITION P8 VALUES LESS THAN(MAXVALUE) TABLESPACE example2 +) +ENABLE ROW MOVEMENT; +``` + +当结果显示为如下信息,则表示创建成功。 + +```sql +CREATE TABLE +``` + + ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) 创建列存分区表的数量建议不超过1000个。 + +- 插入数据 + +将表mogdb_usr.customer_address的数据插入到表mogdb_usr.customer_address_bak中。例如在数据库中创建了一个表mogdb_usr.customer_address的备份表mogdb_usr.customer_address_bak,现在需要将表mogdb_usr.customer_address中的数据插入到表mogdb_usr.customer_address_bak中,则可以执行如下命令。 + +```sql +MogDB=# CREATE TABLE mogdb_usr.customer_address_bak +( + ca_address_sk integer NOT NULL , + ca_address_id character(16) NOT NULL , + ca_street_number character(10) , + ca_street_name character varying(60) , + ca_street_type character(15) , + ca_suite_number character(10) , + ca_city character varying(60) , + ca_county character varying(30) , + ca_state character(2) , + ca_zip character(10) , + ca_country character varying(20) , + ca_gmt_offset numeric(5,2) , + ca_location_type character(20) +) +TABLESPACE example1 +PARTITION BY RANGE (ca_address_sk) +( + PARTITION P1 VALUES LESS THAN(5000), + PARTITION P2 VALUES LESS THAN(10000), + PARTITION P3 VALUES LESS THAN(15000), + PARTITION P4 VALUES LESS THAN(20000), + PARTITION P5 VALUES LESS THAN(25000), + PARTITION P6 VALUES LESS THAN(30000), + PARTITION P7 VALUES LESS THAN(40000), + PARTITION P8 VALUES LESS THAN(MAXVALUE) TABLESPACE example2 +) +ENABLE ROW MOVEMENT; +CREATE TABLE +MogDB=# INSERT INTO mogdb_usr.customer_address_bak SELECT * FROM mogdb_usr.customer_address; +INSERT 0 0 +``` + +- 修改分区表行迁移属性 + +```sql +MogDB=# ALTER TABLE mogdb_usr.customer_address_bak DISABLE ROW MOVEMENT; +ALTER TABLE +``` + +- 删除分区 + +删除分区P8。 + +```sql +MogDB=# ALTER TABLE mogdb_usr.customer_address_bak DROP PARTITION P8; +ALTER TABLE +``` + +- 增加分区 + +增加分区P8,范围为 40000<= P8<=MAXVALUE。 + +```sql +MogDB=# ALTER TABLE mogdb_usr.customer_address_bak ADD PARTITION P8 VALUES LESS THAN (MAXVALUE); +ALTER TABLE +``` + +- 重命名分区 + +重命名分区P8为P_9。 + +```sql +MogDB=# ALTER TABLE mogdb_usr.customer_address_bak RENAME PARTITION P8 TO P_9; +ALTER TABLE +``` + +重命名分区P_9为P8。 + +```sql +MogDB=# ALTER TABLE mogdb_usr.customer_address_bak RENAME PARTITION FOR (40000) TO P8; +ALTER TABLE +``` + +- 修改分区的表空间 + +修改分区P6的表空间为example3。 + +```sql +MogDB=# ALTER TABLE mogdb_usr.customer_address_bak MOVE PARTITION P6 TABLESPACE example3; +ALTER TABLE +``` + +修改分区P4的表空间为example4。 + +```sql +MogDB=# ALTER TABLE mogdb_usr.customer_address_bak MOVE PARTITION P4 TABLESPACE example4; +ALTER TABLE +``` + +- 查询分区 + +查询分区P6。 + +```sql +MogDB=# SELECT * FROM mogdb_usr.customer_address_bak PARTITION (P6); +MogDB=# SELECT * FROM mogdb_usr.customer_address_bak PARTITION FOR (35888); +``` + +- 删除分区表和表空间 + +```sql +MogDB=# DROP TABLE mogdb_usr.customer_address_bak; +DROP TABLE +MogDB=# DROP TABLESPACE example1; +MogDB=# DROP TABLESPACE example2; +MogDB=# DROP TABLESPACE example3; +MogDB=# DROP TABLESPACE example4; +DROP TABLESPACE +``` + +### column设计 + +- 避免与系统表的列名重复。 + +- 字段含义及数据类型要与程序代码设计保持一致。 + +- 所有字段必须要添加comment注释信息。 + +- 能使用数值类型,就不要使用字符类型。 + +- 禁止用字符类型存储日期数据。 + +- 时间类型字段统一使用timestamptz。 + +- 字段尽量要求not null,为字段提供默认值。 + +- MogDB新建数据库默认兼容oracle,not null约束不允许传入空字符串,空字符串默认会转换为null,兼容PG模式的数据库不会有这个问题。 + +### 序列设计 + +- 禁止手动创建与表相关的序列,应指定serial/bingserial类型方式创建。 + +- 序列的步长建议设置为1。 + +- 不建议设置minvalue和maxvalue。 + +- 不建议设置cache,设置cache后序列号不连续。 + +- 禁止开启cycle。 + +- 序列应与代码中变量定义类型及范围一致,防止无法插入数据。 + +### constraint设计 + +#### 主键约束 + +- 每个table必须包含主键。 + +- 建议不要用有业务含义的名称作为主键,比如身份证或者国家名称,尽管其是unique的。 + +- 建议主键的一步到位的写法:`id serial primary key`或`id bigserial primary key`。 + +- 建议内容系统中size较大的table主键的等效写法如下,便于后续维护。 + + ```sql + create table test(id serial not null ); + create unique index CONCURRENTLY ON test (id); + ``` + +#### 唯一约束 + +除主键外,需存在唯一性约束的,可通过创建以“uk_”为前缀的唯一索引实现。 + +#### 外键约束 + +- 存在外键关系的表上尽量创建外键约束。 + +- 性能要求高而安全性自己控制的系统不建议使用外键。 + +- 使用外键时,一定要设置fk的action,例如cascade、set null、set default。 + +#### 非空列 + +- 所有非空列必须添加not null约束 + +#### 检查约束 + +- 对于字段有检查性约束,一般要求指定check规则。例如:性别、状态等字段。 + +### index设计 + +- 频繁DML操作的表索引数量不建议超过5个。 +- create/drop index时添加concurrently参数。 +- 真正创建索引前可以使用虚拟索引确定索引的有效性。 +- 经常出现在关键字order by、group by、distinct后面的字段,建立索引。 +- 经常用作查询选择的字段,建立索引。 +- 经常用作表连接的属性上,建立索引。 +- 复合索引的字段数不建议超过3个。 +- 复合索引得一个字段是常用检索条件。 +- 复合索引第一个字段不应存在单字段索引。 +- 对数据很少被更新的表,经常只查询其中的几个字段,考虑使用索引覆盖。 +- 不要在有大量相同取值的字段上建立索引。 +- 建议用unique index代替unique constraints便于后续维护。 +- 建议对where中带多个字段and条件的高频query,参考数据分布情况,建多个字段的复合index。 +- 无用的索引以及重复索引应删除,避免对执行计划及数据库性能造成负面影响。 + +### view设计 + +- 尽量使用简单视图,尽可能少使用复杂视图。 + + 简单视图定义:数据来自单个表,且无分组(DISTINCT/GROUP BY)、无函数。 + + 复杂视图定义:数据来自多个表,或有分组,有函数,表的个数不能超过3个。 + +- 尽量不要使用嵌套视图,如果必须使用,不能超过2层嵌套。 + +### function设计 + +- 函数必须检索数据库表记录或数据库其他对象,甚至修改(执行Insert、Delete、Update、Drop、Create等操作)数据库信息。 + +- 如果某项功能不需要和数据库打交道,则不得通过数据库函数的方式实现。 + +- 在函数中避免采用DML或DDL语句。 + +## 语法规范 + +### 关于NULL + +- 说明:`NULL`的判断:`IS NULL`、`IS NOT NULL`。 + +- 说明:注意`boolean`类型取值`true`、`false`、`NULL`。 + +- 说明:小心`NOT IN`集合中带有`NULL`元素。 + +- 建议:使用`count(1)`或`count(*)`来统计行数,而不建议使用`count(col)`来统计行数,因为`NULL`值不会计入。 + +- 规则:`count(多列列名)`时,多列列名必须使用括号,例如`count( (col1,col2,col3) )`。 + +- 注意:多列的`count`,即使所有列都为`NULL`,该行也被计数,所以效果与`count(*)`一致。 + +- 注意:`count(distinct col)`计算某列的非`NULL`不重复数量,`NULL`不被计数;`count(distinct (col1,col2,...) )`计算多列的唯一值时,`NULL`会被计数,同时`NULL`与`NULL`会被认为是相同的。 + +- 注意:`NULL`的`count`与`sum` + + ```sql + select count(1), count(a), sum(a) from (SELECT * FROM (VALUES (NULL), (2) ) v(a)) as foo where a is NULL; + count | count | sum + -------+-------+----- + 1 | 0 | + (1 row) + ``` + +- 判断两个值是否相同(将`NULL`视为相同的值) + + ```sql + select null is distinct from null; + ?column? + \--------- + f + (1 row) + + select null is distinct from 1; + ?column? + \--------- + t + (1 row) + + select null is not distinct from null; + ?column? + \--------- + t + (1 row) + + select null is not distinct from 1; + ?column? + \--------- + f + (1 row) + ``` + +### 关于索引失效 + +- 在书写SQL语句时经常会在查询中使用函数及表达式,建议尽量不要在条件列上使用函数及表达式。在条件列上使用函数或者表达式的时候会导致使用不上该条件列上的索引,从而影响SQL的查询效率。尽量把函数或者表达式用在条件值上,避免使用在条件列上。示例: + + ```sql + select name from tab where id+100>1000; + ``` + + 可以改写为如下形式: + + ```sql + select name from tab where id>1000-100; + ``` + +- 查询语句中尽量不要使用左模糊查询。示例: + + ```sql + select id from tab where name like '%ly'; + ``` + +- 查询中尽量不要使用负向查询,如`not in/like`,示例: + + ```sql + select id from tab where name not in ('ly','ty'); + ``` + +### 确保使用到所有变量和参数 + +- 声明变量也会产生一定的系统开销,并会显得代码不够严谨,在编译时未使用的变量会有告警,需修改以确保没有任何告警。 + +## Query操作 + +### DDL操作 + +- 业务高峰期禁止对已存在的表执行任何DDL操作 + +- 所有生产DDL操作必须经过开发测试环境验证 + +- 维护索引时应采用concurrently的方式 + +- 应该使用pg_repack替换vacuum full来重建表 + +- 大表添加带默认值的字段时,应拆分为:添加字段、填补默认值及添加非空约束三部分,如将`alter table t add column col datatype not null default xxx;`分解为如下,避免填充`default`值导致的过长时间锁表 + + ```sql + alter table t add column col datatype ; + alter table t alter column col set default xxx; + update table t set column= DEFAULT where id in ( select id from t where column is null limit + 1000 ) ; \watch 3 + alter table t alter column col set not null; + ``` + +### DML操作 + +- 更新数据的SQL语句禁止出现`where 1=1` + +- 单条DML语句操作的数据量不超过10万 + +- 清空表中的数据时,应使用`truncate` + +- 对于风险性较高的操作,应该显示的开启事务,确认无误后在提交 + +- 事务中SQL逻辑尽量简单,操作执行完后要及时提交,避免`idle in transaction`状态 + +- 大批数据入库时应使用`copy`替换`insert` + +- 数据导入前考虑先删除索引,导入完成后重建 + +### DQL操作 + +- 禁止使用`select *`,应用具体所需字段替换 + +- 禁止使用`where 1=1`,避免全表扫描或笛卡尔积 + +- 检索条件值应该与字段类型保持一致,防止不走索引 + +- 等号左边的字段应该与索引保持一致,尤其是条件索引或函数索引 + +- 关注慢SQL的执行计划,如与预期不一致,尽快修改 + +- 使用`count(*)`或`count(1)`来统计行数,`count(column)`不会统计`null`行 + +- 限制`join`的数量,不建议超过3个 + +- 递归查询需要做好限制,防止无限循环 + +- 对于or运算,应该使用`union all`或`union`替换 + +### 数据导入 + +- 建议大批量的数据入库时,使用`copy`,不建议使用`insert`,以提高写入速度 + +- 导入数据前需要先删除相关索引,导入完成后重建,提高数据导入速度 + +### 事务操作 + +- 事务中的sql逻辑尽可能的简单,让每个事务的粒度尽可能小,尽量lock少的资源,避免lock、deadlock的产生,事务执行完及时提交 + +- 执行CRAETE、DROP、ALTER等DDL操作,尤其多条,不要显式的开transaction,因为加lock的mode非常高,极易产生deadlock + +- state为`idle in transaction`的连接,如果出现在Master,会无谓的lock住相应的资源,可导致后续产生lock,甚至deadlock;出现在Slave,可导致卡住主从同步 + +### 其他 + +- 建议运行在SSD上的实例,random_page_cost(默认值为4)设置为1.0~2.0之间,使查询规划器更倾向于使用索引扫描 + +- 建议在需要使用`explain analyze`查看实际真正执行计划与时间时,如果是写入query,强烈建议先开启事务,然后回滚。 + +- 对于频繁更新,膨胀率较高的表,应找窗口期执行表重组,降低高水位 + +## PostgreSQL兼容性 + +### 建库规范 + +MogDB创建数据库使用PG兼容模式方法如下: + +```sql +create database dbnam DBCOMPATIBILITY='PG' encoding=’utf8’; +``` + +### 数据类型 + +#### 数值类型 + +在开发使用中,MogDB只允许使用smallint、integer、bigint、numeric[(p[,s])]、serial、bigserial这几种类型。 + +| 类型 | PostgreSQL | MogDB | 存储尺寸 | 备注 | +| ---------------- | ---------- | ----- | ------------ | ------------------------------------------------------- | +| tinyint | / | 支持 | 1字节 | 0 ~ 255 | +| smallint | 支持 | 支持 | 2字节 | -32,768 ~ +32,767 | +| integer | 支持 | 支持 | 4字节 | -2,147,483,648 ~ +2,147,483,647 | +| binary_integer | / | 支持 | / | integer别名 | +| bigint | 支持 | 支持 | 8字节 | -9,223,372,036,854,775,808 ~ +9,223,372,036,854,775,807 | +| decimal[(p[,s])] | 支持 | 支持 | 可变字节 | 最高小数点前131072位,以及小数点后16383位 | +| numeric[(p[,s])] | 支持 | 支持 | 可变字节 | 最高小数点前131072位,以及小数点后16383位 | +| number[(p[,s])] | / | 支持 | / | numeric别名 | +| real | 支持 | 支持 | 4字节 | 6位十进制数字精度 | +| float4 | / | 支持 | 4字节 | 6位十进制数字精度 | +| double precision | 支持 | 支持 | 8字节 | 15位十进制数字精度 | +| binary_double | / | 支持 | 8字节 | double precision别名 | +| float8 | / | 支持 | 8字节 | 15位十进制数字精度 | +| float[(p )] | / | 支持 | 4字节或8字节 | | +| dec[(p,[s])] | / | 支持 | / | 最高小数点前131072位,以及小数点后16383位 | +| integer[(p,[s])] | / | 支持 | / | 最高小数点前131072位,以及小数点后16383位 | +| smallserial | 支持 | 支持 | 2字节 | 1 ~ 32,767 | +| serial | 支持 | 支持 | 4字节 | 1 ~ 2,147,483,647 | +| bigserial | 支持 | 支持 | 8字节 | 1 ~ 9,223,372,036,854,775,807 | +| tinyint | / | 支持 | 1字节 | 0 ~ 255 | + +#### 字符类型 + +在开发使用中,MogDB只允许使用char(n)、varchar(n)、text字符类型。 + +| 类型 | PostgreSQL | MogDB | 存储尺寸 | 备注 | +| ------------ | ---------- | ----- | ----------------------------- | ------------------------------------------------------------ | +| char(n) | 支持 | 支持 | pg中最大为1GB,og中最大为10MB | pg中n指字符数量,og中n指字节数量,兼容pg模式配置下n代表字符数量 | +| nchar(n) | / | 支持 | 最大为10MB | n指字节数量,兼容pg模式配置下n代表字符数量 | +| varchar(n) | 支持 | 支持 | pg中最大为1GB,og中最大为10MB | pg中n指字符数量,og中n指字节数量,兼容pg模式配置下n代表字符数量 | +| varchar2(n) | / | 支持 | 最大为10MB | varchar(n)别名 | +| nvarchar2(n) | / | 支持 | 最大为10MB | n指字符数量 | +| text | 支持 | 支持 | 1GB - 1 | | +| clob | / | 支持 | 1GB - 1 | text别名 | + +#### 时间类型 + +在开发使用中,MogDB只允许使用`timestamp[(p)][with time zone]`、`date`期类型。 + +| 类型 | PostgreSQL | MogDB | 存储尺寸 | 备注 | +| ----------------------------------- | ---------- | --------- | -------- | ------------------------------------------------------- | +| timestamp[(p )][without time zone] | 支持 | 支持 | 8字节 | 4713 BC - 294276 AD | +| timestamp[(p )][with time zone] | 支持 | 支持 | 8字节 | 4713 BC - 294276 AD | +| date | 支持 | 支持 | 4字节 | 4713 BC - 5874897 AD (og实际存储空间大小为8字节) | +| time[(p )][without time zone] | 支持 | 支持 | 8字节 | 00:00:00 - 24:00:00 | +| time[(p )][with time zone] | 支持 | 支持 | 12字节 | 00:00:00+1459 - 24:00:00-1459 | +| interval[fields][(p )] | 支持 | 支持 | 16字节 | -178000000年 - 178000000年 | +| smalldatetime | / | 支持 | 8字节 | 日期和时间,不带时区,精确到分钟,秒位大于等于30秒进一位 | +| interval day(1) to second(p) | / | 支持 | 16字节 | | +| reltime | / | 支持 | 4字节 | | + +#### json类型 + +MogDB只允许使用json类型。 + +| 类型 | PostgreSQL | MogDB | 存储尺寸 | 备注 | +| ----- | ---------- | ----------- | -------- | ---- | +| json | 支持 | 支持 | / | | +| jsonb | 支持 | 2.1开始支持 | / | | + +### 关键字 + +PostgreSQL与MogDB数据库中关键字差异化说明,保留是指数据库保留关键字,不允许自定义使用;非保留或空是指可以自定义使用,MogDB保留字详情,请参考[此页面](../../reference-guide/sql-reference/2-keywords.md)。 + +| 关键字 | MogDB | PostgreSQL | +| ------------- | ------------------------ | ------------------------ | +| AUTHID | 保留 | #N/A | +| BUCKETS | 保留 | #N/A | +| COMPACT | 保留 | #N/A | +| DATE | 非保留(不能是函数或类型) | | +| DELTAMERGE | 保留 | #N/A | +| EXCLUDED | 保留 | #N/A | +| FENCED | 保留 | #N/A | +| GROUPING | | 非保留(不能是函数或类型) | +| HDFSDIRECTORY | 保留 | #N/A | +| IS | 保留 | 保留(可以是函数或类型) | +| ISNULL | 非保留 | 保留(可以是函数或类型) | +| LATERAL | | 保留 | +| LESS | 保留 | #N/A | +| MAXVALUE | 保留 | 非保留 | +| MINUS | 保留 | #N/A | +| MODIFY | 保留 | #N/A | +| NLSSORT | 保留 | #N/A | +| NUMBER | 非保留(不能是函数或类型) | | +| PERFORMANCE | 保留 | #N/A | +| PROCEDURE | 保留 | 非保留 | +| REJECT | 保留 | #N/A | +| ROWNUM | 保留 | #N/A | +| SYSDATE | 保留 | #N/A | +| VERIFY | 保留 | #N/A | + +### 隐式转换异同 + +| input_type | target_type | MogDB | PG | +| ----------- | ------------------------------------------------------------ | ---------------- | -------------------------------------------------------- | +| bool | int2、int4、int8 | 支持 | int4不支持,其它无 | +| int2 | bool、text、bpchar、varchar、interval | 支持(bpchar无) | 无 | +| int4 | bool、int2、text、bpchar、varchar、interval | 支持(bpchar无) | bool不支持,int2为in assignment,其它无 | +| int8 | bool、text、bpchar、varchar | 支持(bpchar无) | 无 | +| text | int8、int4、int2、float4、float8、date、timestamp、nemeric | 支持 | 无 | +| float4 | int8、int4、int2、text、bpchar、varchar | 支持(bpchar无) | 前三in assignment,后无 | +| float8 | int8、int4、int2、text、float4、bpchar、varchar、interval、numeric | 支持(bpchar无) | int8、int4、int2、float4、numeric为in assignment,其它无 | +| bpchar | int8、int4、date、timestamp、numeric | | | +| date | text、bpchar、varchar | 支持(bpchar无) | 无 | +| timestamp | text、varchar | 支持 | 无 | +| timestamptz | text | 支持 | 无 | +| numeric | int8、int4、int2、text、bpchar、varchar、interval | 支持(bpchar无) | 前三in assignment,后无 | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/1-development-based-on-jdbc-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/1-development-based-on-jdbc-overview.md new file mode 100644 index 00000000..1bab561f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/1-development-based-on-jdbc-overview.md @@ -0,0 +1,10 @@ +--- +title: 概述 +summary: 概述 +author: Guo Huan +date: 2021-04-26 +--- + +# 概述 + +JDBC(Java Database Connectivity,Java数据库连接)是一种用于执行SQL语句的Java API,可以为多种关系数据库提供统一访问接口,应用程序可基于它操作数据。 MogDB库提供了对JDBC 4.0特性的支持,需要使用JDK1.8版本编译程序代码,不支持JDBC桥接ODBC方式。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/10-example-common-operations.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/10-example-common-operations.md new file mode 100644 index 00000000..ecc3ca70 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/10-example-common-operations.md @@ -0,0 +1,286 @@ +--- +title: 示例:常用操作 +summary: 示例:常用操作 +author: Guo Huan +date: 2021-04-26 +--- + +# 示例:常用操作 + +
+ +## 示例1 + +此示例将演示如何基于MogDB提供的JDBC接口开发应用程序。 + +```java +//DBtest.java +//演示基于JDBC开发的主要步骤,会涉及创建数据库、创建表、插入数据等。 + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.PreparedStatement; +import java.sql.SQLException; +import java.sql.Statement; +import java.sql.CallableStatement; +import java.sql.Types; + +public class DBTest { + + //创建数据库连接。 + public static Connection GetConnection(String username, String passwd) { + String driver = "org.opengauss.Driver"; + String sourceURL = "jdbc:opengauss://localhost:8000/postgres"; + Connection conn = null; + try { + //加载数据库驱动。 + Class.forName(driver).newInstance(); + } catch (Exception e) { + e.printStackTrace(); + return null; + } + + try { + //创建数据库连接。 + conn = DriverManager.getConnection(sourceURL, username, passwd); + System.out.println("Connection succeed!"); + } catch (Exception e) { + e.printStackTrace(); + return null; + } + + return conn; + }; + + //执行普通SQL语句,创建customer_t1表。 + public static void CreateTable(Connection conn) { + Statement stmt = null; + try { + stmt = conn.createStatement(); + + //执行普通SQL语句。 + int rc = stmt + .executeUpdate("CREATE TABLE customer_t1(c_customer_sk INTEGER, c_customer_name VARCHAR(32));"); + + stmt.close(); + } catch (SQLException e) { + if (stmt != null) { + try { + stmt.close(); + } catch (SQLException e1) { + e1.printStackTrace(); + } + } + e.printStackTrace(); + } + } + + //执行预处理语句,批量插入数据。 + public static void BatchInsertData(Connection conn) { + PreparedStatement pst = null; + + try { + //生成预处理语句。 + pst = conn.prepareStatement("INSERT INTO customer_t1 VALUES (?,?)"); + for (int i = 0; i < 3; i++) { + //添加参数。 + pst.setInt(1, i); + pst.setString(2, "data " + i); + pst.addBatch(); + } + //执行批处理。 + pst.executeBatch(); + pst.close(); + } catch (SQLException e) { + if (pst != null) { + try { + pst.close(); + } catch (SQLException e1) { + e1.printStackTrace(); + } + } + e.printStackTrace(); + } + } + + //执行预编译语句,更新数据。 + public static void ExecPreparedSQL(Connection conn) { + PreparedStatement pstmt = null; + try { + pstmt = conn + .prepareStatement("UPDATE customer_t1 SET c_customer_name = ? WHERE c_customer_sk = 1"); + pstmt.setString(1, "new Data"); + int rowcount = pstmt.executeUpdate(); + pstmt.close(); + } catch (SQLException e) { + if (pstmt != null) { + try { + pstmt.close(); + } catch (SQLException e1) { + e1.printStackTrace(); + } + } + e.printStackTrace(); + } + } + + +//执行存储过程。 + public static void ExecCallableSQL(Connection conn) { + CallableStatement cstmt = null; + try { + // 存储过程TESTPROC需提前创建。 + cstmt=conn.prepareCall("{? = CALL TESTPROC(?,?,?)}"); + cstmt.setInt(2, 50); + cstmt.setInt(1, 20); + cstmt.setInt(3, 90); + cstmt.registerOutParameter(4, Types.INTEGER); //注册out类型的参数,类型为整型。 + cstmt.execute(); + int out = cstmt.getInt(4); //获取out参数 + System.out.println("The CallableStatment TESTPROC returns:"+out); + cstmt.close(); + } catch (SQLException e) { + if (cstmt != null) { + try { + cstmt.close(); + } catch (SQLException e1) { + e1.printStackTrace(); + } + } + e.printStackTrace(); + } + } + + + /** + * 主程序,逐步调用各静态方法。 + * @param args + */ + public static void main(String[] args) { + //创建数据库连接。 + Connection conn = GetConnection("tester", "Password1234"); + + //创建表。 + CreateTable(conn); + + //批插数据。 + BatchInsertData(conn); + + //执行预编译语句,更新数据。 + ExecPreparedSQL(conn); + + //执行存储过程。 + ExecCallableSQL(conn); + + //关闭数据库连接。 + try { + conn.close(); + } catch (SQLException e) { + e.printStackTrace(); + } + + } + +} +``` + +
+ +## 示例2 客户端内存占用过多解决 + +此示例主要使用setFetchSize来调整客户端内存使用,它的原理是通过数据库游标来分批获取服务器端数据,但它会加大网络交互,可能会损失部分性能。 + +由于游标事务内有效,故需要先关闭自动提交,最后需要执行手动提交。 + +```java +// 关闭掉自动提交 +conn.setAutoCommit(false); +Statement st = conn.createStatement(); + +// 打开游标,每次获取50行数据 +st.setFetchSize(50); +ResultSet rs = st.executeQuery("SELECT * FROM mytable"); +while (rs.next()) +{ + System.out.print("a row was returned."); +} +conn.commit(); +rs.close(); + +// 关闭服务器游标。 +st.setFetchSize(0); +rs = st.executeQuery("SELECT * FROM mytable"); +while (rs.next()) +{ + System.out.print("many rows were returned."); +} +conn.commit(); +rs.close(); + +// Close the statement. +st.close(); +conn.close(); +``` + +执行完毕后可使用如下命令恢复自动提交: + +```java +conn.setAutoCommit(true); +``` + +
+ +## 示例3 常用数据类型使用示例 + +```java +//bit类型使用示例,注意此处bit类型取值范围[0,1] +Statement st = conn.createStatement(); +String sqlstr = "create or replace function fun_1()\n" + + "returns bit AS $$\n" + + "select col_bit from t_bit limit 1;\n" + + "$$\n" + + "LANGUAGE SQL;"; +st.execute(sqlstr); +CallableStatement c = conn.prepareCall("{ ? = call fun_1() }"); +//注册输出类型,位串类型 +c.registerOutParameter(1, Types.BIT); +c.execute(); +//使用Boolean类型获取结果 +System.out.println(c.getBoolean(1)); + +// money类型使用示例 +// 表结构中包含money类型列的使用示例。 +st.execute("create table t_money(col1 money)"); +PreparedStatement pstm = conn.prepareStatement("insert into t_money values(?)"); +// 使用PGobject赋值,取值范围[-92233720368547758.08,92233720368547758.07] +PGobject minMoney = new PGobject(); +minMoney.setType("money"); +minMoney.setValue("-92233720368547758.08"); +pstm.setObject(1, minMoney); +pstm.execute(); +// 使用PGMoney赋值,取值范围[-9999999.99,9999999.99] +pstm.setObject(1,new PGmoney(9999999.99)); +pstm.execute(); + +// 函数返回值为money的使用示例。 +st.execute("create or replace function func_money() " + + "return money " + + "as declare " + + "var1 money; " + + "begin " + + " select col1 into var1 from t_money limit 1; " + + " return var1; " + + "end;"); +CallableStatement cs = conn.prepareCall("{? = call func_money()}"); +cs.registerOutParameter(1,Types.DOUBLE); +cs.execute(); +cs.getObject(1); +``` + +
+ +## 示例4 获取驱动版本示例 + +```java +Driver.getGSVersion(); +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/11-example-retrying-sql-queries-for-applications.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/11-example-retrying-sql-queries-for-applications.md new file mode 100644 index 00000000..184cbd92 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/11-example-retrying-sql-queries-for-applications.md @@ -0,0 +1,205 @@ +--- +title: 示例:重新执行应用SQL +summary: 示例:重新执行应用SQL +author: Guo Huan +date: 2021-04-26 +--- + +# 示例:重新执行应用SQL + +当主数据库节点故障且10s未恢复时,MogDB会将对应的备数据库节点升主,使MogDB正常运行。备升主期间正在运行的作业会失败;备升主后启动的作业不会再受影响。如果要做到数据库节点主备切换过程中,上层业务不感知,可参考此示例构建业务层SQL重试机制。 + +```java +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.PreparedStatement; +import java.sql.ResultSet; +import java.sql.SQLException; +import java.sql.Statement; + +class ExitHandler extends Thread { + private Statement cancel_stmt = null; + + public ExitHandler(Statement stmt) { + super("Exit Handler"); + this.cancel_stmt = stmt; + } + public void run() { + System.out.println("exit handle"); + try { + this.cancel_stmt.cancel(); + } catch (SQLException e) { + System.out.println("cancel query failed."); + e.printStackTrace(); + } + } +} + +public class SQLRetry { + //创建数据库连接。 + public static Connection GetConnection(String username, String passwd) { + String driver = "org.opengauss.Driver"; + String sourceURL = "jdbc:opengauss://10.131.72.136:8000/postgres"; + Connection conn = null; + try { + //加载数据库驱动。 + Class.forName(driver).newInstance(); + } catch (Exception e) { + e.printStackTrace(); + return null; + } + + try { + //创建数据库连接。 + conn = DriverManager.getConnection(sourceURL, username, passwd); + System.out.println("Connection succeed!"); + } catch (Exception e) { + e.printStackTrace(); + return null; + } + + return conn; +} + + //执行普通SQL语句,创建jdbc_test1表。 + public static void CreateTable(Connection conn) { + Statement stmt = null; + try { + stmt = conn.createStatement(); + + + Runtime.getRuntime().addShutdownHook(new ExitHandler(stmt)); + + //执行普通SQL语句。 + int rc2 = stmt + .executeUpdate("DROP TABLE if exists jdbc_test1;"); + + int rc1 = stmt + .executeUpdate("CREATE TABLE jdbc_test1(col1 INTEGER, col2 VARCHAR(10));"); + + stmt.close(); + } catch (SQLException e) { + if (stmt != null) { + try { + stmt.close(); + } catch (SQLException e1) { + e1.printStackTrace(); + } + } + e.printStackTrace(); + } + } + + //执行预处理语句,批量插入数据。 + public static void BatchInsertData(Connection conn) { + PreparedStatement pst = null; + + try { + //生成预处理语句。 + pst = conn.prepareStatement("INSERT INTO jdbc_test1 VALUES (?,?)"); + for (int i = 0; i < 100; i++) { + //添加参数。 + pst.setInt(1, i); + pst.setString(2, "data " + i); + pst.addBatch(); + } + //执行批处理。 + pst.executeBatch(); + pst.close(); + } catch (SQLException e) { + if (pst != null) { + try { + pst.close(); + } catch (SQLException e1) { + e1.printStackTrace(); + } + } + e.printStackTrace(); + } + } + + //执行预编译语句,更新数据。 + private static boolean QueryRedo(Connection conn){ + PreparedStatement pstmt = null; + boolean retValue = false; + try { + pstmt = conn + .prepareStatement("SELECT col1 FROM jdbc_test1 WHERE col2 = ?"); + + pstmt.setString(1, "data 10"); + ResultSet rs = pstmt.executeQuery(); + + while (rs.next()) { + System.out.println("col1 = " + rs.getString("col1")); + } + rs.close(); + + pstmt.close(); + retValue = true; + } catch (SQLException e) { + System.out.println("catch...... retValue " + retValue); + if (pstmt != null) { + try { + pstmt.close(); + } catch (SQLException e1) { + e1.printStackTrace(); + } + } + e.printStackTrace(); + } + + System.out.println("finesh......"); + return retValue; + } + + //查询语句,执行失败重试,重试次数可配置。 + public static void ExecPreparedSQL(Connection conn) throws InterruptedException { + int maxRetryTime = 50; + int time = 0; + String result = null; + do { + time++; + try { + System.out.println("time:" + time); + boolean ret = QueryRedo(conn); + if(ret == false){ + System.out.println("retry, time:" + time); + Thread.sleep(10000); + QueryRedo(conn); + } + } catch (Exception e) { + e.printStackTrace(); + } + } while (null == result && time < maxRetryTime); + + } + + /** + * 主程序,逐步调用各静态方法。 + * @param args + * @throws InterruptedException + */ + public static void main(String[] args) throws InterruptedException { + //创建数据库连接。 + Connection conn = GetConnection("testuser", "test@123"); + + //创建表。 + CreateTable(conn); + + //批插数据。 + BatchInsertData(conn); + + //执行预编译语句,更新数据。 + ExecPreparedSQL(conn); + + //关闭数据库连接。 + try { + conn.close(); + } catch (SQLException e) { + e.printStackTrace(); + } + + } + + } +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/12-example-importing-and-exporting-data-through-local-files.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/12-example-importing-and-exporting-data-through-local-files.md new file mode 100644 index 00000000..32dd2795 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/12-example-importing-and-exporting-data-through-local-files.md @@ -0,0 +1,119 @@ +--- +title: 示例:通过本地文件导入导出数据 +summary: 示例:通过本地文件导入导出数据 +author: Guo Huan +date: 2021-04-26 +--- + +# 示例:通过本地文件导入导出数据 + +在使用JAVA语言基于MogDB进行二次开发时,可以使用CopyManager接口,通过流方式,将数据库中的数据导出到本地文件或者将本地文件导入数据库中,文件格式支持CSV、TEXT等格式。 + +样例程序如下,执行时需要加载MogDB JDBC驱动。 + +```java +import java.sql.Connection; +import java.sql.DriverManager; +import java.io.IOException; +import java.io.FileInputStream; +import java.io.FileOutputStream; +import java.sql.SQLException; +import org.opengauss.copy.CopyManager; +import org.opengauss.core.BaseConnection; + +public class Copy{ + + public static void main(String[] args) + { + String urls = new String("jdbc:opengauss://10.180.155.74:8000/postgres"); //数据库URL + String username = new String("jack"); //用户名 + String password = new String("Enmo@123"); //密码 + String tablename = new String("migration_table"); //定义表信息 + String tablename1 = new String("migration_table_1"); //定义表信息 + String driver = "org.opengauss.Driver"; + Connection conn = null; + + try { + Class.forName(driver); + conn = DriverManager.getConnection(urls, username, password); + } catch (ClassNotFoundException e) { + e.printStackTrace(System.out); + } catch (SQLException e) { + e.printStackTrace(System.out); + } + + // 将SELECT * FROM migration_table查询结果导出到本地文件d:/data.txt + try { + copyToFile(conn, "d:/data.txt", "(SELECT * FROM migration_table)"); + } catch (SQLException e) { + k + e.printStackTrace(); + } catch (IOException e) { + + e.printStackTrace(); + } + //将d:/data.txt中的数据导入到migration_table_1中。 + try { + copyFromFile(conn, "d:/data.txt", tablename1); + } catch (SQLException e) { + e.printStackTrace(); + } catch (IOException e) { + + e.printStackTrace(); + } + + // 将migration_table_1中的数据导出到本地文件d:/data1.txt + try { + copyToFile(conn, "d:/data1.txt", tablename1); + } catch (SQLException e) { + + e.printStackTrace(); + } catch (IOException e) { + + + e.printStackTrace(); + } + } + // 使用copyIn把数据从文件中导入数据库, + public static void copyFromFile(Connection connection, String filePath, String tableName) + throws SQLException, IOException { + + FileInputStream fileInputStream = null; + + try { + CopyManager copyManager = new CopyManager((BaseConnection)connection); + fileInputStream = new FileInputStream(filePath); + copyManager.copyIn("COPY " + tableName + " FROM STDIN", fileInputStream); + } finally { + if (fileInputStream != null) { + try { + fileInputStream.close(); + } catch (IOException e) { + e.printStackTrace(); + } + } + } + } + + // 使用copyOut把数据从数据库中导出到文件中 + public static void copyToFile(Connection connection, String filePath, String tableOrQuery) + throws SQLException, IOException { + + FileOutputStream fileOutputStream = null; + + try { + CopyManager copyManager = new CopyManager((BaseConnection)connection); + fileOutputStream = new FileOutputStream(filePath); + copyManager.copyOut("COPY " + tableOrQuery + " TO STDOUT", fileOutputStream); + } finally { + if (fileOutputStream != null) { + try { + fileOutputStream.close(); + } catch (IOException e) { + e.printStackTrace(); + } + } + } + } +} +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/13-example-2-migrating-data-from-a-my-database-to-mogdb.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/13-example-2-migrating-data-from-a-my-database-to-mogdb.md new file mode 100644 index 00000000..d72ad90a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/13-example-2-migrating-data-from-a-my-database-to-mogdb.md @@ -0,0 +1,98 @@ +--- +title: 示例:从MY向MogDB进行数据迁移 +summary: 示例:从MY向MogDB进行数据迁移 +author: Guo Huan +date: 2021-04-26 +--- + +# 示例:从MY向MogDB进行数据迁移 + +下面示例演示如何通过CopyManager从MY向MogDB进行数据迁移的过程。 + +```java +import java.io.StringReader; +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.ResultSet; +import java.sql.SQLException; +import java.sql.Statement; + +import org.opengauss.copy.CopyManager; +import org.opengauss.core.BaseConnection; + +public class Migration{ + + public static void main(String[] args) { + String url = new String("jdbc:opengauss://10.180.155.74:8000/postgres"); //数据库URL + String user = new String("jack"); //MogDB用户名 + String pass = new String("Enmo@123"); //MogDB密码 + String tablename = new String("migration_table"); //定义表信息 + String delimiter = new String("|"); //定义分隔符 + String encoding = new String("UTF8"); //定义字符集 + String driver = "org.opengauss.Driver"; + StringBuffer buffer = new StringBuffer(); //定义存放格式化数据的缓存 + + try { + //获取源数据库查询结果集 + ResultSet rs = getDataSet(); + + //遍历结果集,逐行获取记录 + //将每条记录中各字段值,按指定分隔符分割,由换行符结束,拼成一个字符串 + //把拼成的字符串,添加到缓存buffer + while (rs.next()) { + buffer.append(rs.getString(1) + delimiter + + rs.getString(2) + delimiter + + rs.getString(3) + delimiter + + rs.getString(4) + + "\n"); + } + rs.close(); + + try { + //建立目标数据库连接 + Class.forName(driver); + Connection conn = DriverManager.getConnection(url, user, pass); + BaseConnection baseConn = (BaseConnection) conn; + baseConn.setAutoCommit(false); + + //初始化表信息 + String sql = "Copy " + tablename + " from STDIN DELIMITER " + "'" + delimiter + "'" + " ENCODING " + "'" + encoding + "'"; + + //提交缓存buffer中的数据 + CopyManager cp = new CopyManager(baseConn); + StringReader reader = new StringReader(buffer.toString()); + cp.copyIn(sql, reader); + baseConn.commit(); + reader.close(); + baseConn.close(); + } catch (ClassNotFoundException e) { + e.printStackTrace(System.out); + } catch (SQLException e) { + e.printStackTrace(System.out); + } + + } catch (Exception e) { + e.printStackTrace(); + } + } + + //******************************** + // 从源数据库返回查询结果集 + //********************************* + private static ResultSet getDataSet() { + ResultSet rs = null; + try { + Class.forName("com.MY.jdbc.Driver").newInstance(); + Connection conn = DriverManager.getConnection("jdbc:MY://10.119.179.227:3306/jack?useSSL=false&allowPublicKeyRetrieval=true", "jack", "Enmo@123"); + Statement stmt = conn.createStatement(); + rs = stmt.executeQuery("select * from migration_table"); + } catch (SQLException e) { + e.printStackTrace(); + } catch (Exception e) { + e.printStackTrace(); + } + return rs; + } +} + +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/14-example-logic-replication-code.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/14-example-logic-replication-code.md new file mode 100644 index 00000000..830e3ed7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/14-example-logic-replication-code.md @@ -0,0 +1,166 @@ +--- +title: 示例:逻辑复制代码示例 +summary: 示例:逻辑复制代码示例 +author: Guo Huan +date: 2021-04-26 +--- + +# 示例:逻辑复制代码示例 + +下面示例演示如何通过JDBC接口使用逻辑复制功能的过程。 + +针对逻辑复制的配置选项,除了在[逻辑解码](../../logical-replication/logical-decoding/1-logical-decoding.md)中的配置选项外,还有专门给JDBC流式解码增加的配置项,如下所示: + +1. 解码线程并发度 + + 通过配置选项parallel-decode-num,指定并行解码的Decoder线程数量。其取值范围为1~20的int型,取1表示按照原有的串行逻辑进行解码,取其余值即为开启并行解码。默认值为1。当该选项配置为1时,禁止配置解码格式decode-style。 + +2. 解码格式 + + 通过配置选项decode-style,指定解码格式。其取值为char型的字符'j'、't'或'b',分别代表json格式、text格式及二进制格式。默认值为'b'即二进制格式解码。该选项仅允许并行解码时设置,且二进制格式解码仅在并行解码场景下支持。 + +> **说明**: +> 二进制格式编码规则如下所示: +> +> 1. 前4字节代表接下来到语句级别分隔符字母P(不含)或者该批次结束符F(不含)的解码结果的总字节数,该值如果为0代表本批次解码结束。 +> 2. 接下来8字节uint64代表lsn。 +> 3. 接下来1字节的字母有5种B/C/I/U/D,分别代表begin/commit/insert/update/delete。 +> 4. 第3步字母为B时: +> a. 接下来的8字节uint64代表CSN。 +> b. 接下来的8字节uint64代表commit_lsn。 +> c. 【该部分为可选项】接下来的1字节字母如果为T,则代表后面4字节uint32表示该事务commit时间戳长度,再后面等同于该长度的字符为时间戳字符串。 +> d. 因为之后仍可能有解码语句,接下来会有1字节字母P或F作为语句间的分隔符,P代表本批次仍有解码的语句,F代表本批次完成。 +> 5. 第3步字母为C时: +> a. 【该部分为可选项】接下来1字节字母如果为X,则代表后面的8字节uint64表示xid。 +> b. 【该部分为可选项】接下来的1字节字母如果为T,则代表后面4字节uint32表示时间戳长度,再后面等同于该长度的字符为时间戳字符串。 +> c. 因为批量发送日志时,一个COMMIT日志解码之后可能仍有其他事务的解码结果,接下来的1字节字母如果为P则表示该批次仍需解码,如果为F则表示该批次解码结束。 +> 6. 第3步字母为I/U/D时: +> a. 接下来的2字节uint16代表schema名的长度。 +> b. 按照上述长度读取schema名。 +> c. 接下来的2字节uint16代表table名的长度。 +> d. 按照上述长度读取table名。 +> e. 【该部分为可选项】接下来1字符字母如果为N代表为新元组,如果为O代表为旧元组,这里先发送新元组。 +> i. 接下来的2字节uint16代表该元组需要解码的列数,记为attrnum。 +> ii. 以下流程重复attrnum次。 +> 1). 接下来2字节uint16代表列名的长度。 +> 2). 按照上述长度读取列名。 +> 3). 接下来4字节uint32代表当前列类型的Oid。 +> 4). 接下来4字节uint32代表当前列的值(以字符串格式存储)的长度,如果为0xFFFFFFFF则表示NULL,如果为0则表示长度为0的字符串。 +> 5). 按照上述长度读取列值。 +> f. 因为之后仍可能有解码语句,接下来的1字节字母如果为P则表示该批次仍需解码,如果为F则表示该批次解码结束。 + +1. 限制仅备机解码 + + 通过配置选项standby-connection,指定是否限制仅备机解码。其取值为bool型(可用0或1表示),取true(或1)代表限制仅允许连接备机解码,连接主机解码时会报错退出;取false(或0)时不做限制。默认值为false(0)。 + +2. 批量发送 + + 通过配置选项batch-sending,指定是否批量发送。其取值范围为0或1的int型,取0表示逐条发送解码结果,取1表示解码结果累积到达1MB则批量发送解码结果。默认值为0。该选项仅允许并行解码时设置。开启批量发送的场景中,当解码格式为'j'或't'时,在原来的每条解码语句之前会附加一个uint32类型,表示本条解码结果长度(长度不包含当前的uint32类型),以及一个uint64类型,表示当前解码结果对应的lsn。 + +在并行解码的标准场景下(16核CPU、内存128G、网络带宽 > 200MBps、表的列数为10-100、单行数据量0.1KB~1KB、DML操作以insert为主、不涉及落盘事务即单个事务中语句数量小于4096、parallel_decode_num为8、解码格式为'b'且开启批量发送功能),解码性能(这里以xlog消耗量为标准)不低于100MBps。为保证解码性能达标以及尽量降低对业务影响,一台备机上应尽量仅建立一个并行解码连接,保证CPU、内存、带宽资源充足。 + +```java +//逻辑复制功能示例:文件名,LogicalReplicationDemo.java +//前提条件:添加JDBC用户机器IP到数据库白名单里,在pg_hba.conf添加以下内容即可: +//假设JDBC用户IP为10.10.10.10 +//host all all 10.10.10.10/32 sha256 +//host replication all 10.10.10.10/32 sha256 + +import org.opengauss.PGProperty; +import org.opengauss.jdbc.PgConnection; +import org.opengauss.replication.LogSequenceNumber; +import org.opengauss.replication.PGReplicationStream; + +import java.nio.ByteBuffer; +import java.sql.DriverManager; +import java.util.Properties; +import java.util.concurrent.TimeUnit; + +public class LogicalReplicationDemo { + public static void main(String[] args) { + String driver = "org.opengauss.Driver"; + //此处配置数据库IP以及端口,这里的端口为haPort,通常默认是所连接DN的port+1端口 + String sourceURL = "jdbc:opengauss://$ip:$port/postgres"; + PgConnection conn = null; + //默认逻辑复制槽的名称是:replication_slot + //测试模式:创建逻辑复制槽 + int TEST_MODE_CREATE_SLOT = 1; + //测试模式:开启逻辑复制(前提条件是逻辑复制槽已经存在) + int TEST_MODE_START_REPL = 2; + //测试模式:删除逻辑复制槽 + int TEST_MODE_DROP_SLOT = 3; + //开启不同的测试模式 + int testMode = TEST_MODE_START_REPL; + + try { + Class.forName(driver); + } catch (Exception e) { + e.printStackTrace(); + return; + } + + try { + Properties properties = new Properties(); + PGProperty.USER.set(properties, "user"); + PGProperty.PASSWORD.set(properties, "passwd"); + //对于逻辑复制,以下三个属性是必须配置项 + PGProperty.ASSUME_MIN_SERVER_VERSION.set(properties, "9.4"); + PGProperty.REPLICATION.set(properties, "database"); + PGProperty.PREFER_QUERY_MODE.set(properties, "simple"); + conn = (PgConnection) DriverManager.getConnection(sourceURL, properties); + System.out.println("connection success!"); + + if(testMode == TEST_MODE_CREATE_SLOT){ + conn.getReplicationAPI() + .createReplicationSlot() + .logical() + .withSlotName("replication_slot") + .withOutputPlugin("mppdb_decoding") + .make(); + }else if(testMode == TEST_MODE_START_REPL) { + //开启此模式前需要创建复制槽 + LogSequenceNumber waitLSN = LogSequenceNumber.valueOf("6F/E3C53568"); + PGReplicationStream stream = conn + .getReplicationAPI() + .replicationStream() + .logical() + .withSlotName("replication_slot") + .withSlotOption("include-xids", false) + .withSlotOption("skip-empty-xacts", true) + .withStartPosition(waitLSN) + .withSlotOption("parallel-decode-num", 10) //解码线程并发度 + .withSlotOption("white-table-list", "public.t1,public.t2") //白名单列表 + .withSlotOption("standby-connection", true) //强制备机解码 + .withSlotOption("decode-style", "t") //解码格式 + .withSlotOption("sending-bacth", 1) //批量发送解码结果 + .start(); + while (true) { + ByteBuffer byteBuffer = stream.readPending(); + + if (byteBuffer == null) { + TimeUnit.MILLISECONDS.sleep(10L); + continue; + } + + int offset = byteBuffer.arrayOffset(); + byte[] source = byteBuffer.array(); + int length = source.length - offset; + System.out.println(new String(source, offset, length)); + + //如果需要flush lsn,根据业务实际情况调用以下接口 + //LogSequenceNumber lastRecv = stream.getLastReceiveLSN(); + //stream.setFlushedLSN(lastRecv); + //stream.forceUpdateStatus(); + + } + }else if(testMode == TEST_MODE_DROP_SLOT){ + conn.getReplicationAPI() + .dropReplicationSlot("replication_slot"); + } + } catch (Exception e) { + e.printStackTrace(); + return; + } + } +} +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/14.1-example-parameters-for-connecting-to-the-database-in-different-scenarios.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/14.1-example-parameters-for-connecting-to-the-database-in-different-scenarios.md new file mode 100644 index 00000000..2351da3d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/14.1-example-parameters-for-connecting-to-the-database-in-different-scenarios.md @@ -0,0 +1,78 @@ +--- +title: 不同场景下连接数据库参数配置 +summary: 不同场景下连接数据库参数配置 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 示例:不同场景下连接数据库参数配置 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 以下示例场景中node代表“host:port”,host为数据库服务器名称或IP地址,port为数据库服务器端口。 + +## 容灾场景 + +某客户有两套数据库数据库实例,其中A数据库实例为生产数据库实例,B数据库实例为容灾数据库实例。当客户执行容灾切换时,A数据库实例将降为容灾数据库实例,B数据库实例将升为生产数据库实例。此时为了避免修改配置文件导致的应用重启或重新发版。客户可在初始配置文件时,即将A、B数据库实例写入连接串中。此时在主数据库实例不可连接时,驱动将尝试对容灾数据库实例建连。例如A数据库实例为{node1,node2,node3}。B数据库实例为{node4,node5,node6}。 + +则url可参考如下进行配置: + +```java +jdbc:opengauss://node1,node2,node3,node4,node5,node6/database?priorityServers=3 +``` + +## 负载均衡场景 + +某客户存在一套集中式数据库实例,包含1主2备三个节点{node1,node2,node3},其中node1为主节点,node2、node3为备节点。 + +客户希望同一应用程序上建立的连接,较为均匀的分布在三个节点上,则url可参考如下配置: + +```java +jdbc:opengauss://node1,node2,node3/database?loadBalanceHosts=true +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** 使用loadBalanceHosts时,若连接建立在备DN上,将无法执行写操作。如果业务需要执行读写操作,请勿配置该参数。 + +## 日志诊断场景 + +某客户在使用中出现数据导入慢或出现一些难以分析的异常报错,可通过开启trace日志进行诊断,url可参考如下进行配置。 + +``` +jdbc:opengauss://node1/database?loggerLevel=trace&loggerFile=jdbc.log +``` + +## 高性能场景 + +某客户对于相同sql可能多次执行,仅是传参不同,为了提升执行效率,可开启prepareThreshold参数,避免重复生成执行计划,url可参考如下配置。 + +```java +jdbc:opengauss://node1/database?prepareThreshold=5 +``` + +某客户一次查询1000万数据,为避免同时返回造成内存溢出,可使用defaultRowFetchSize,url可参考如下配置。 + +```java +jdbc:opengauss://node1/database?defaultRowFetchSize=50000 +``` + +某客户需要批量插入1000万数据,为提升效率,可使用batchMode,url可参考如下配置。 + +```java +jdbc:opengauss://node1/database?batchMode=true +``` + +## 大小写转换场景 + +在oracle中元数据的默认存储为大写,而在MogDB中元数据默认存储为小写,所以在从oracle迁移到MogDB后,原本大写的元数据会变为小写。如果原本业务中涉及到大写元数据的处理,可以开启此参数,但是不建议通过这种方式来解决问题,最好通过修改业务编码来解决。如果一定要使用,请务必确认当前数据库中的元数据是否全为小写,以避免出现问题。 + +``` +jdbc:opengauss://node1/database?uppercaseAttributeName=true +``` + +对于DatabaseMetaData中涉及的接口,按照入参直接调用即可,对于ResultSetMetaData中涉及的接口使用方法如下所示 + +``` +Statement stmt = conn.createStatement(); +ResultSet rs = stmt.executeQuery("select * from test_supper"); +ResultSetMetaData rsmd = rs.getMetaData(); +for (int i = 1; i <= rsmd.getColumnCount(); i++) { + System.out.println(rsmd.getColumnLabel(i) + " " + rsmd.getColumnName(i)); +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/1-java-sql-Connection.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/1-java-sql-Connection.md new file mode 100644 index 00000000..b90cd0c0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/1-java-sql-Connection.md @@ -0,0 +1,67 @@ +--- +title: java.sql.Connection +summary: java.sql.Connection +author: Guo Huan +date: 2021-05-17 +--- + +# java.sql.Connection + +java.sql.Connection是数据库连接接口。 + +**表 1** 对java.sql.Connection接口的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :----------------------------------------------------------- | :------------------------------- | :--------- | +| abort(Executor executor) | void | Yes | +| clearWarnings() | void | Yes | +| close() | void | Yes | +| commit() | void | Yes | +| createArrayOf(String typeName, Object[] elements) | Array | Yes | +| createBlob() | Blob | Yes | +| createClob() | Clob | Yes | +| createSQLXML() | SQLXML | Yes | +| createStatement() | Statement | Yes | +| createStatement(int resultSetType, int resultSetConcurrency) | Statement | Yes | +| createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) | Statement | Yes | +| getAutoCommit() | Boolean | Yes | +| getCatalog() | String | Yes | +| getClientInfo() | Properties | Yes | +| getClientInfo(String name) | String | Yes | +| getHoldability() | int | Yes | +| getMetaData() | DatabaseMetaData | Yes | +| getNetworkTimeout() | int | Yes | +| getSchema() | String | Yes | +| getTransactionIsolation() | int | Yes | +| getTypeMap() | Map<String,Class<?>> | Yes | +| getWarnings() | SQLWarning | Yes | +| isClosed() | Boolean | Yes | +| isReadOnly() | Boolean | Yes | +| isValid(int timeout) | boolean | Yes | +| nativeSQL(String sql) | String | Yes | +| prepareCall(String sql) | CallableStatement | Yes | +| prepareCall(String sql, int resultSetType, int resultSetConcurrency) | CallableStatement | Yes | +| prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) | CallableStatement | Yes | +| prepareStatement(String sql) | PreparedStatement | Yes | +| prepareStatement(String sql, int autoGeneratedKeys) | PreparedStatement | Yes | +| prepareStatement(String sql, int[] columnIndexes) | PreparedStatement | Yes | +| prepareStatement(String sql, int resultSetType, int resultSetConcurrency) | PreparedStatement | Yes | +| prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) | PreparedStatement | Yes | +| prepareStatement(String sql, String[] columnNames) | PreparedStatement | Yes | +| releaseSavepoint(Savepoint savepoint) | void | Yes | +| rollback() | void | Yes | +| rollback(Savepoint savepoint) | void | Yes | +| setAutoCommit(boolean autoCommit) | void | Yes | +| setClientInfo(Properties properties) | void | Yes | +| setClientInfo(String name,String value) | void | Yes | +| setHoldability(int holdability) | void | Yes | +| setNetworkTimeout(Executor executor, int milliseconds) | void | Yes | +| setReadOnly(boolean readOnly) | void | Yes | +| setSavepoint() | Savepoint | Yes | +| setSavepoint(String name) | Savepoint | Yes | +| setSchema(String schema) | void | Yes | +| setTransactionIsolation(int level) | void | Yes | +| setTypeMap(Map<String,Class<?>> map) | void | Yes | + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: +> 接口内部默认使用自动提交模式,若通过setAutoCommit(false)关闭自动提交,将会导致后面执行的语句都受到显式事务包裹,数据库中不支持事务中执行的语句不能在此模式下执行。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/10-javax-sql-DataSource.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/10-javax-sql-DataSource.md new file mode 100644 index 00000000..f4da542d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/10-javax-sql-DataSource.md @@ -0,0 +1,21 @@ +--- +title: javax.sql.DataSource +summary: javax.sql.DataSource +author: Guo Huan +date: 2021-05-17 +--- + +# javax.sql.DataSource + +javax.sql.DataSource是数据源接口。 + +**表 1** 对javax.sql.DataSource接口的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :--------------------------------------------- | :---------- | :--------- | +| getConneciton() | Connection | Yes | +| getConnection(String username,String password) | Connection | Yes | +| getLoginTimeout() | int | Yes | +| getLogWriter() | PrintWriter | Yes | +| setLoginTimeout(int seconds) | void | Yes | +| setLogWriter(PrintWriter out) | void | Yes | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/11-javax-sql-PooledConnection.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/11-javax-sql-PooledConnection.md new file mode 100644 index 00000000..24e81358 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/11-javax-sql-PooledConnection.md @@ -0,0 +1,19 @@ +--- +title: javax.sql.PooledConnection +summary: javax.sql.PooledConnection +author: Guo Huan +date: 2021-05-17 +--- + +# javax.sql.PooledConnection + +javax.sql.PooledConnection是由连接池创建的连接接口。 + +**表 1** 对javax.sql.PooledConnection的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :----------------------------------------------------------- | :--------- | :--------- | +| addConnectionEventListener (ConnectionEventListener listener) | void | Yes | +| close() | void | Yes | +| getConnection() | Connection | Yes | +| removeConnectionEventListener (ConnectionEventListener listener) | void | Yes | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/12-javax-naming-Context.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/12-javax-naming-Context.md new file mode 100644 index 00000000..1e5b534e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/12-javax-naming-Context.md @@ -0,0 +1,25 @@ +--- +title: javax.naming.Context +summary: javax.naming.Context +author: Guo Huan +date: 2021-05-17 +--- + +# javax.naming.Context + +javax.naming.Context是连接配置的上下文接口。 + +**表 1** 对javax.naming.Context的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :------------------------------------- | :--------- | :--------- | +| bind(Name name, Object obj) | void | Yes | +| bind(String name, Object obj) | void | Yes | +| lookup(Name name) | Object | Yes | +| lookup(String name) | Object | Yes | +| rebind(Name name, Object obj) | void | Yes | +| rebind(String name, Object obj) | void | Yes | +| rename(Name oldName, Name newName) | void | Yes | +| rename(String oldName, String newName) | void | Yes | +| unbind(Name name) | void | Yes | +| unbind(String name) | void | Yes | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/13-javax-naming-spi-InitialContextFactory.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/13-javax-naming-spi-InitialContextFactory.md new file mode 100644 index 00000000..8db2b4c8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/13-javax-naming-spi-InitialContextFactory.md @@ -0,0 +1,16 @@ +--- +title: javax.naming.spi.InitialContextFactory +summary: javax.naming.spi.InitialContextFactory +author: Guo Huan +date: 2021-05-17 +--- + +# javax.naming.spi.InitialContextFactory + +javax.naming.spi.InitialContextFactory是初始连接上下文工厂接口。 + +**表 1** 对javax.naming.spi.InitialContextFactory的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :-------------------------------------------------- | :--------- | :--------- | +| getInitialContext(Hashtable<?,?> environment) | Context | Yes | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/14-CopyManager.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/14-CopyManager.md new file mode 100644 index 00000000..ac85f9ba --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/14-CopyManager.md @@ -0,0 +1,47 @@ +--- +title: CopyManager +summary: CopyManager +author: Guo Huan +date: 2021-05-17 +--- + +# CopyManager + +CopyManager是MogDB JDBC驱动中提供的一个API接口类,用于批量向MogDB中导入数据。 + +
+ +## CopyManager的继承关系 + +CopyManager类位于org.opengauss.copy Package中,继承自java.lang.Object类,该类的声明如下: + +```java +public class CopyManager +extends Object +``` + +
+ +## 构造方法 + +```java +public CopyManager(BaseConnection connection) +throws SQLException +``` + +
+ +## 常用方法 + +**表 1** CopyManager常用方法 + +| 返回值 | 方法 | 描述 | throws | +| :----------------------- | :---------------- | :-------------- | :------------- | +| CopyIn | copyIn(String sql) | - | SQLException | +| long | copyIn(String sql, InputStream from) | 使用COPY FROM STDIN从InputStream中快速向数据库中的表加载数据。 | SQLException,IOException | +| long | copyIn(String sql, InputStream from, int bufferSize) | 使用COPY FROM STDIN从InputStream中快速向数据库中的表加载数据。 | SQLException,IOException | +| long | copyIn(String sql, Reader from) | 使用COPY FROM STDIN从Reader中快速向数据库中的表加载数据。 | SQLException,IOException | +| long | copyIn(String sql, Reader from, int bufferSize) | 使用COPY FROM STDIN从Reader中快速向数据库中的表加载数据。 | SQLException,IOException | +| CopyOut | copyOut(String sql) | - | SQLException | +| long | copyOut(String sql, OutputStream to) | 将一个COPY TO STDOUT的结果集从数据库发送到OutputStream类中。 | SQLException,IOException | +| long | copyOut(String sql, Writer to) | 将一个COPY TO STDOUT的结果集从数据库发送到Writer类中。 | SQLException,IOException | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/2-java-sql-CallableStatement.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/2-java-sql-CallableStatement.md new file mode 100644 index 00000000..f74ce9f4 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/2-java-sql-CallableStatement.md @@ -0,0 +1,46 @@ +--- +title: java.sql.CallableStatement +summary: java.sql.CallableStatement +author: Guo Huan +date: 2021-05-17 +--- + +# java.sql.CallableStatement + +java.sql.CallableStatement是存储过程执行接口。 + +**表 1** 对java.sql.CallableStatement的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :------------------------------------------------- | :--------- | :--------- | +| getArray(int parameterIndex) | Array | Yes | +| getBigDecimal(int parameterIndex) | BigDecimal | Yes | +| getBlob(int parameterIndex) | Blob | Yes | +| getBoolean(int parameterIndex) | boolean | Yes | +| getByte(int parameterIndex) | byte | Yes | +| getBytes(int parameterIndex) | byte[] | Yes | +| getClob(int parameterIndex) | Clob | Yes | +| getDate(int parameterIndex) | Date | Yes | +| getDate(int parameterIndex, Calendar cal) | Date | Yes | +| getDouble(int parameterIndex) | double | Yes | +| getFloat(int parameterIndex) | float | Yes | +| getInt(int parameterIndex) | int | Yes | +| getLong(int parameterIndex) | long | Yes | +| getObject(int parameterIndex) | Object | Yes | +| getObject(int parameterIndex, Class<T> type) | Object | Yes | +| getShort(int parameterIndex) | short | Yes | +| getSQLXML(int parameterIndex) | SQLXML | Yes | +| getString(int parameterIndex) | String | Yes | +| getNString(int parameterIndex) | String | Yes | +| getTime(int parameterIndex) | Time | Yes | +| getTime(int parameterIndex, Calendar cal) | Time | Yes | +| getTimestamp(int parameterIndex) | Timestamp | Yes | +| getTimestamp(int parameterIndex, Calendar cal) | Timestamp | Yes | +| registerOutParameter(int parameterIndex, int type) | void | Yes | +| wasNull() | Boolean | Yes | + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 不允许含有OUT参数的语句执行批量操作。 +> - 以下方法是从java.sql.Statement继承而来:close,execute,executeQuery,executeUpdate,getConnection,getResultSet,getUpdateCount,isClosed,setMaxRows , setFetchSize。 +> - 以下方法是从java.sql.PreparedStatement继承而来:addBatch,clearParameters,execute,executeQuery,executeUpdate,getMetaData,setBigDecimal,setBoolean,setByte,setBytes,setDate,setDouble,setFloat,setInt,setLong,setNull,setObject,setString,setTime,setTimestamp 。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/3-java-sql-DatabaseMetaData.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/3-java-sql-DatabaseMetaData.md new file mode 100644 index 00000000..8616361c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/3-java-sql-DatabaseMetaData.md @@ -0,0 +1,217 @@ +--- +title: java.sql.DatabaseMetaData +summary: java.sql.DatabaseMetaData +author: Guo Huan +date: 2021-05-17 +--- + +# java.sql.DatabaseMetaData + +java.sql.DatabaseMetaData是数据库对象定义接口。 + +**表 1** 对java.sql.DatabaseMetaData的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :----------------------------------------------------------- | :----------- | :--------- | +| allProceduresAreCallable() | boolean | Yes | +| allTablesAreSelectable() | boolean | Yes | +| autoCommitFailureClosesAllResultSets() | boolean | Yes | +| dataDefinitionCausesTransactionCommit() | boolean | Yes | +| dataDefinitionIgnoredInTransactions() | boolean | Yes | +| deletesAreDetected(int type) | boolean | Yes | +| doesMaxRowSizeIncludeBlobs() | boolean | Yes | +| generatedKeyAlwaysReturned() | boolean | Yes | +| getBestRowIdentifier(String catalog, String schema, String table, int scope, boolean nullable) | ResultSet | Yes | +| getCatalogs() | ResultSet | Yes | +| getCatalogSeparator() | String | Yes | +| getCatalogTerm() | String | Yes | +| getClientInfoProperties() | ResultSet | Yes | +| getColumnPrivileges(String catalog, String schema, String table, String columnNamePattern) | ResultSet | Yes | +| getConnection() | Connection | Yes | +| getCrossReference(String parentCatalog, String parentSchema, String parentTable, String foreignCatalog, String foreignSchema, String foreignTable) | ResultSet | Yes | +| getDefaultTransactionIsolation() | int | Yes | +| getExportedKeys(String catalog, String schema, String table) | ResultSet | Yes | +| getExtraNameCharacters() | String | Yes | +| getFunctionColumns(String catalog, String schemaPattern, String functionNamePattern, String columnNamePattern) | ResultSet | Yes | +| getFunctions(String catalog, String schemaPattern, String functionNamePattern) | ResultSet | Yes | +| getIdentifierQuoteString() | String | Yes | +| getImportedKeys(String catalog, String schema, String table) | ResultSet | Yes | +| getIndexInfo(String catalog, String schema, String table, boolean unique, boolean approximate) | ResultSet | Yes | +| getMaxBinaryLiteralLength() | int | Yes | +| getMaxCatalogNameLength() | int | Yes | +| getMaxCharLiteralLength() | int | Yes | +| getMaxColumnNameLength() | int | Yes | +| getMaxColumnsInGroupBy() | int | Yes | +| getMaxColumnsInIndex() | int | Yes | +| getMaxColumnsInOrderBy() | int | Yes | +| getMaxColumnsInSelect() | int | Yes | +| getMaxColumnsInTable() | int | Yes | +| getMaxConnections() | int | Yes | +| getMaxCursorNameLength() | int | Yes | +| getMaxIndexLength() | int | Yes | +| getMaxLogicalLobSize() | default long | Yes | +| getMaxProcedureNameLength() | int | Yes | +| getMaxRowSize() | int | Yes | +| getMaxSchemaNameLength() | int | Yes | +| getMaxStatementLength() | int | Yes | +| getMaxStatements() | int | Yes | +| getMaxTableNameLength() | int | Yes | +| getMaxTablesInSelect() | int | Yes | +| getMaxUserNameLength() | int | Yes | +| getNumericFunctions() | String | Yes | +| getPrimaryKeys(String catalog, String schema, String table) | ResultSet | Yes | +| getPartitionTablePrimaryKeys(String catalog, String schema, String table) | ResultSet | Yes | +| getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern) | ResultSet | Yes | +| getProcedures(String catalog, String schemaPattern, String procedureNamePattern) | ResultSet | Yes | +| getProcedureTerm() | String | Yes | +| getSchemas() | ResultSet | Yes | +| getSchemas(String catalog, String schemaPattern) | ResultSet | Yes | +| getSchemaTerm() | String | Yes | +| getSearchStringEscape() | String | Yes | +| getSQLKeywords() | String | Yes | +| getSQLStateType() | int | Yes | +| getStringFunctions() | String | Yes | +| getSystemFunctions() | String | Yes | +| getTablePrivileges(String catalog, String schemaPattern, String tableNamePattern) | ResultSet | Yes | +| getTimeDateFunctions() | String | Yes | +| getTypeInfo() | ResultSet | Yes | +| getUDTs(String catalog, String schemaPattern, String typeNamePattern, int[] types) | ResultSet | Yes | +| getURL() | String | Yes | +| getVersionColumns(String catalog, String schema, String table) | ResultSet | Yes | +| insertsAreDetected(int type) | boolean | Yes | +| locatorsUpdateCopy() | boolean | Yes | +| othersDeletesAreVisible(int type) | boolean | Yes | +| othersInsertsAreVisible(int type) | boolean | Yes | +| othersUpdatesAreVisible(int type) | boolean | Yes | +| ownDeletesAreVisible(int type) | boolean | Yes | +| ownInsertsAreVisible(int type) | boolean | Yes | +| ownUpdatesAreVisible(int type) | boolean | Yes | +| storesLowerCaseIdentifiers() | boolean | Yes | +| storesMixedCaseIdentifiers() | boolean | Yes | +| storesUpperCaseIdentifiers() | boolean | Yes | +| supportsBatchUpdates() | boolean | Yes | +| supportsCatalogsInDataManipulation() | boolean | Yes | +| supportsCatalogsInIndexDefinitions() | boolean | Yes | +| supportsCatalogsInPrivilegeDefinitions() | boolean | Yes | +| supportsCatalogsInProcedureCalls() | boolean | Yes | +| supportsCatalogsInTableDefinitions() | boolean | Yes | +| supportsCorrelatedSubqueries() | boolean | Yes | +| supportsDataDefinitionAndDataManipulationTransactions() | boolean | Yes | +| supportsDataManipulationTransactionsOnly() | boolean | Yes | +| supportsGetGeneratedKeys() | boolean | Yes | +| supportsMixedCaseIdentifiers() | boolean | Yes | +| supportsMultipleOpenResults() | boolean | Yes | +| supportsNamedParameters() | boolean | Yes | +| supportsOpenCursorsAcrossCommit() | boolean | Yes | +| supportsOpenCursorsAcrossRollback() | boolean | Yes | +| supportsOpenStatementsAcrossCommit() | boolean | Yes | +| supportsOpenStatementsAcrossRollback() | boolean | Yes | +| supportsPositionedDelete() | boolean | Yes | +| supportsPositionedUpdate() | boolean | Yes | +| supportsRefCursors() | boolean | Yes | +| supportsResultSetConcurrency(int type, int concurrency) | boolean | Yes | +| supportsResultSetType(int type) | boolean | Yes | +| supportsSchemasInIndexDefinitions() | boolean | Yes | +| supportsSchemasInPrivilegeDefinitions() | boolean | Yes | +| supportsSchemasInProcedureCalls() | boolean | Yes | +| supportsSchemasInTableDefinitions() | boolean | Yes | +| supportsSelectForUpdate() | boolean | Yes | +| supportsStatementPooling() | boolean | Yes | +| supportsStoredFunctionsUsingCallSyntax() | boolean | Yes | +| supportsStoredProcedures() | boolean | Yes | +| supportsSubqueriesInComparisons() | boolean | Yes | +| supportsSubqueriesInExists() | boolean | Yes | +| supportsSubqueriesInIns() | boolean | Yes | +| supportsSubqueriesInQuantifieds() | boolean | Yes | +| supportsTransactionIsolationLevel(int level) | boolean | Yes | +| supportsTransactions() | boolean | Yes | +| supportsUnion() | boolean | Yes | +| supportsUnionAll() | boolean | Yes | +| updatesAreDetected(int type) | boolean | Yes | +| getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) | ResultSet | Yes | +| getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) | ResultSet | Yes | +| getTableTypes() | ResultSet | Yes | +| getUserName() | String | Yes | +| isReadOnly() | boolean | Yes | +| nullsAreSortedHigh() | boolean | Yes | +| nullsAreSortedLow() | boolean | Yes | +| nullsAreSortedAtStart() | boolean | Yes | +| nullsAreSortedAtEnd() | boolean | Yes | +| getDatabaseProductName() | String | Yes | +| getDatabaseProductVersion() | String | Yes | +| getDriverName() | String | Yes | +| getDriverVersion() | String | Yes | +| getDriverMajorVersion() | int | Yes | +| getDriverMinorVersion() | int | Yes | +| usesLocalFiles() | boolean | Yes | +| usesLocalFilePerTable() | boolean | Yes | +| supportsMixedCaseIdentifiers() | boolean | Yes | +| storesUpperCaseIdentifiers() | boolean | Yes | +| storesLowerCaseIdentifiers() | boolean | Yes | +| supportsMixedCaseQuotedIdentifiers() | boolean | Yes | +| storesUpperCaseQuotedIdentifiers() | boolean | Yes | +| storesLowerCaseQuotedIdentifiers() | boolean | Yes | +| storesMixedCaseQuotedIdentifiers() | boolean | Yes | +| supportsAlterTableWithAddColumn() | boolean | Yes | +| supportsAlterTableWithDropColumn() | boolean | Yes | +| supportsColumnAliasing() | boolean | Yes | +| nullPlusNonNullIsNull() | boolean | Yes | +| supportsConvert() | boolean | Yes | +| supportsConvert(int fromType, int toType) | boolean | Yes | +| supportsTableCorrelationNames() | boolean | Yes | +| supportsDifferentTableCorrelationNames() | boolean | Yes | +| supportsExpressionsInOrderBy() | boolean | Yes | +| supportsOrderByUnrelated() | boolean | Yes | +| supportsGroupBy() | boolean | Yes | +| supportsGroupByUnrelated() | boolean | Yes | +| supportsGroupByBeyondSelect() | boolean | Yes | +| supportsLikeEscapeClause() | boolean | Yes | +| supportsMultipleResultSets() | boolean | Yes | +| supportsMultipleTransactions() | boolean | Yes | +| supportsNonNullableColumns() | boolean | Yes | +| supportsMinimumSQLGrammar() | boolean | Yes | +| supportsCoreSQLGrammar() | boolean | Yes | +| supportsExtendedSQLGrammar() | boolean | Yes | +| supportsANSI92EntryLevelSQL() | boolean | Yes | +| supportsANSI92IntermediateSQL() | boolean | Yes | +| supportsANSI92FullSQL() | boolean | Yes | +| supportsIntegrityEnhancementFacility() | boolean | Yes | +| supportsOuterJoins() | boolean | Yes | +| supportsFullOuterJoins() | boolean | Yes | +| supportsLimitedOuterJoins() | boolean | Yes | +| isCatalogAtStart() | boolean | Yes | +| supportsSchemasInDataManipulation() | boolean | Yes | +| supportsSavepoints() | boolean | Yes | +| supportsResultSetHoldability(int holdability) | boolean | Yes | +| getResultSetHoldability() | int | Yes | +| getDatabaseMajorVersion() | int | Yes | +| getDatabaseMinorVersion() | int | Yes | +| getJDBCMajorVersion() | int | Yes | +| getJDBCMinorVersion() | int | Yes | + +> **说明**: +> +> uppercaseAttributeName为true时,以下接口会将查询结果转为大写,可转换范围与java中的toUpperCase方法一致。 +> +> - public ResultSet getProcedures(String catalog, String schemaPattern, String procedureNamePattern) +> - public ResultSet getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern) +> - public ResultSet getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) +> - public ResultSet getSchemas(String catalog, String schemaPattern) +> - public ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) +> - public ResultSet getColumnPrivileges(String catalog, String schema, String table, String columnNamePattern) +> - public ResultSet getTablePrivileges(String catalog, String schemaPattern, String tableNamePattern) +> - public ResultSet getBestRowIdentifier(String catalog, String schema, String table, int scope, boolean nullable) +> - public ResultSet getPrimaryKeys(String catalog, String schema, String table) +> - protected ResultSet getImportedExportedKeys(String primaryCatalog, String primarySchema, String primaryTable, String foreignCatalog, String foreignSchema, String foreignTable) +> - public ResultSet getIndexInfo(String catalog, String schema, String tableName, boolean unique, boolean approximate) +> - public ResultSet getUDTs(String catalog, String schemaPattern, String typeNamePattern, int[] types) +> - public ResultSet getFunctions(String catalog, String schemaPattern, String functionNamePattern) + +> **注意:** +> +> getPartitionTablePrimaryKeys(String catalog, String schema, String table)接口用于获取分区表含全局索引的主键列,使用示例如下: +> +> ``` +> PgDatabaseMetaData dbmd = (PgDatabaseMetaData)conn.getMetaData(); +> dbmd.getPartitionTablePrimaryKeys("catalogName", "schemaName", "tableName"); +> ``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/4-java-sql-Driver.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/4-java-sql-Driver.md new file mode 100644 index 00000000..1c6f1b7b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/4-java-sql-Driver.md @@ -0,0 +1,22 @@ +--- +title: java.sql.Driver +summary: java.sql.Driver +author: Guo Huan +date: 2021-05-17 +--- + +# java.sql.Driver + +java.sql.Driver是数据库驱动接口。 + +**表 1** 对java.sql.Driver的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :------------------------------------------- | :------------------- | :--------- | +| acceptsURL(String url) | Boolean | Yes | +| connect(String url, Properties info) | Connection | Yes | +| jdbcCompliant() | Boolean | Yes | +| getMajorVersion() | int | Yes | +| getMinorVersion() | int | Yes | +| getParentLogger() | Logger | Yes | +| getPropertyInfo(String url, Properties info) | DriverPropertyInfo[] | Yes | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/5-java-sql-PreparedStatement.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/5-java-sql-PreparedStatement.md new file mode 100644 index 00000000..238f803f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/5-java-sql-PreparedStatement.md @@ -0,0 +1,70 @@ +--- +title: java.sql.PreparedStatement +summary: java.sql.PreparedStatement +author: Guo Huan +date: 2021-05-17 +--- + +# java.sql.PreparedStatement + +java.sql.PreparedStatement是预处理语句接口。 + +**表 1** 对java.sql.PreparedStatement的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :----------------------------------------------------------- | :---------------- | :--------- | +| clearParameters() | void | Yes | +| execute() | Boolean | Yes | +| executeQuery() | ResultSet | Yes | +| excuteUpdate() | int | Yes | +| executeLargeUpdate() | long | No | +| getMetaData() | ResultSetMetaData | Yes | +| getParameterMetaData() | ParameterMetaData | Yes | +| setArray(int parameterIndex, Array x) | void | Yes | +| setAsciiStream(int parameterIndex, InputStream x, int length) | void | Yes | +| setBinaryStream(int parameterIndex, InputStream x) | void | Yes | +| setBinaryStream(int parameterIndex, InputStream x, int length) | void | Yes | +| setBinaryStream(int parameterIndex, InputStream x, long length) | void | Yes | +| setBlob(int parameterIndex, InputStream inputStream) | void | Yes | +| setBlob(int parameterIndex, InputStream inputStream, long length) | void | Yes | +| setBlob(int parameterIndex, Blob x) | void | Yes | +| setCharacterStream(int parameterIndex, Reader reader) | void | Yes | +| setCharacterStream(int parameterIndex, Reader reader, int length) | void | Yes | +| setClob(int parameterIndex, Reader reader) | void | Yes | +| setClob(int parameterIndex, Reader reader, long length) | void | Yes | +| setClob(int parameterIndex, Clob x) | void | Yes | +| setDate(int parameterIndex, Date x, Calendar cal) | void | Yes | +| setNull(int parameterIndex, int sqlType) | void | Yes | +| setNull(int parameterIndex, int sqlType, String typeName) | void | Yes | +| setObject(int parameterIndex, Object x) | void | Yes | +| setObject(int parameterIndex, Object x, int targetSqlType) | void | Yes | +| setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength) | void | Yes | +| setSQLXML(int parameterIndex, SQLXML xmlObject) | void | Yes | +| setTime(int parameterIndex, Time x) | void | Yes | +| setTime(int parameterIndex, Time x, Calendar cal) | void | Yes | +| setTimestamp(int parameterIndex, Timestamp x) | void | Yes | +| setTimestamp(int parameterIndex, Timestamp x, Calendar cal) | void | Yes | +| setUnicodeStream(int parameterIndex, InputStream x, int length) | void | Yes | +| setURL(int parameterIndex, URL x) | void | Yes | +| setBoolean(int parameterIndex, boolean x) | void | Yes | +| setBigDecimal(int parameterIndex, BigDecimal x) | void | Yes | +| setByte(int parameterIndex, byte x) | void | Yes | +| setBytes(int parameterIndex, byte[] x) | void | Yes | +| setDate(int parameterIndex, Date x) | void | Yes | +| setDouble(int parameterIndex, double x) | void | Yes | +| setFloat(int parameterIndex, float x) | void | Yes | +| setInt(int parameterIndex, int x) | void | Yes | +| setLong(int parameterIndex, long x) | void | Yes | +| setShort(int parameterIndex, short x) | void | Yes | +| setString(int parameterIndex, String x) | void | Yes | +| setNString(int parameterIndex, String x) | void | Yes | +| addBatch() | void | Yes | +| executeBatch() | int[] | Yes | + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - addBatch()、execute()必须在clearBatch()之后才能执行。 +> - 调用executeBatch()方法并不会清除batch。用户必须显式使用clearBatch()清除 。 +> - 在添加了一个batch的绑定变量后,用户若想重用这些值(再次添加一个batch),无需再次使用set*()方法 。 +> - 以下方法是从java.sql.Statement继承而来:close,execute,executeQuery,executeUpdate,getConnection,getResultSet,getUpdateCount,isClosed,setMaxRows, setFetchSize。 +> - executeLargeUpdate()方法必须在JDBC4.2及以上使用。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/6-java-sql-ResultSet.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/6-java-sql-ResultSet.md new file mode 100644 index 00000000..5a009523 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/6-java-sql-ResultSet.md @@ -0,0 +1,154 @@ +--- +title: java.sql.ResultSet +summary: java.sql.ResultSet +author: Guo Huan +date: 2021-05-17 +--- + +# java.sql.ResultSet + +java.sql.ResultSet是执行结果集接口。 + +**表 1** 对java.sql.ResultSet的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :----------------------------------------------------------- | :---------------- | :--------- | +| absolute(int row) | Boolean | Yes | +| afterLast() | void | Yes | +| beforeFirst() | void | Yes | +| cancelRowUpdates() | void | Yes | +| clearWarnings() | void | Yes | +| close() | void | Yes | +| deleteRow() | void | Yes | +| findColumn(String columnLabel) | int | Yes | +| first() | Boolean | Yes | +| getArray(int columnIndex) | Array | Yes | +| getArray(String columnLabel) | Array | Yes | +| getAsciiStream(int columnIndex) | InputStream | Yes | +| getAsciiStream(String columnLabel) | InputStream | Yes | +| getBigDecimal(int columnIndex) | BigDecimal | Yes | +| getBigDecimal(String columnLabel) | BigDecimal | Yes | +| getBinaryStream(int columnIndex) | InputStream | Yes | +| getBinaryStream(String columnLabel) | InputStream | Yes | +| getBlob(int columnIndex) | Blob | Yes | +| getBlob(String columnLabel) | Blob | Yes | +| getBoolean(int columnIndex) | Boolean | Yes | +| getBoolean(String columnLabel) | Boolean | Yes | +| getByte(int columnIndex) | byte | Yes | +| getBytes(int columnIndex) | byte[] | Yes | +| getByte(String columnLabel) | byte | Yes | +| getBytes(String columnLabel) | byte[] | Yes | +| getCharacterStream(int columnIndex) | Reader | Yes | +| getCharacterStream(String columnLabel) | Reader | Yes | +| getClob(int columnIndex) | Clob | Yes | +| getClob(String columnLabel) | Clob | Yes | +| getConcurrency() | int | Yes | +| getCursorName() | String | Yes | +| getDate(int columnIndex) | Date | Yes | +| getDate(int columnIndex, Calendar cal) | Date | Yes | +| getDate(String columnLabel) | Date | Yes | +| getDate(String columnLabel, Calendar cal) | Date | Yes | +| getDouble(int columnIndex) | double | Yes | +| getDouble(String columnLabel) | double | Yes | +| getFetchDirection() | int | Yes | +| getFetchSize() | int | Yes | +| getFloat(int columnIndex) | float | Yes | +| getFloat(String columnLabel) | float | Yes | +| getInt(int columnIndex) | int | Yes | +| getInt(String columnLabel) | int | Yes | +| getLong(int columnIndex) | long | Yes | +| getLong(String columnLabel) | long | Yes | +| getMetaData() | ResultSetMetaData | Yes | +| getObject(int columnIndex) | Object | Yes | +| getObject(int columnIndex, Class<T> type) | <T> T | Yes | +| getObject(int columnIndex, Map<String,Class<?>> map) | Object | Yes | +| getObject(String columnLabel) | Object | Yes | +| getObject(String columnLabel, Class<T> type) | <T> T | Yes | +| getObject(String columnLabel, Map<String,Class<?>> map) | Object | Yes | +| getRow() | int | Yes | +| getShort(int columnIndex) | short | Yes | +| getShort(String columnLabel) | short | Yes | +| getSQLXML(int columnIndex) | SQLXML | Yes | +| getSQLXML(String columnLabel) | SQLXML | Yes | +| getStatement() | Statement | Yes | +| getString(int columnIndex) | String | Yes | +| getString(String columnLabel) | String | Yes | +| getNString(int columnIndex) | String | Yes | +| getNString(String columnLabel) | String | Yes | +| getTime(int columnIndex) | Time | Yes | +| getTime(int columnIndex, Calendar cal) | Time | Yes | +| getTime(String columnLabel) | Time | Yes | +| getTime(String columnLabel, Calendar cal) | Time | Yes | +| getTimestamp(int columnIndex) | Timestamp | Yes | +| getTimestamp(int columnIndex, Calendar cal) | Timestamp | Yes | +| getTimestamp(String columnLabel) | Timestamp | Yes | +| getTimestamp(String columnLabel, Calendar cal) | Timestamp | Yes | +| getType() | int | Yes | +| getWarnings() | SQLWarning | Yes | +| insertRow() | void | Yes | +| isAfterLast() | Boolean | Yes | +| isBeforeFirst() | Boolean | Yes | +| isClosed() | Boolean | Yes | +| isFirst() | Boolean | Yes | +| isLast() | Boolean | Yes | +| last() | Boolean | Yes | +| moveToCurrentRow() | void | Yes | +| moveToInsertRow() | void | Yes | +| next() | Boolean | Yes | +| previous() | Boolean | Yes | +| refreshRow() | void | Yes | +| relative(int rows) | Boolean | Yes | +| rowDeleted() | Boolean | Yes | +| rowInserted() | Boolean | Yes | +| rowUpdated() | Boolean | Yes | +| setFetchDirection(int direction) | void | Yes | +| setFetchSize(int rows) | void | Yes | +| updateArray(int columnIndex, Array x) | void | Yes | +| updateArray(String columnLabel, Array x) | void | Yes | +| updateAsciiStream(int columnIndex, InputStream x, int length) | void | Yes | +| updateAsciiStream(String columnLabel, InputStream x, int length) | void | Yes | +| updateBigDecimal(int columnIndex, BigDecimal x) | void | Yes | +| updateBigDecimal(String columnLabel, BigDecimal x) | void | Yes | +| updateBinaryStream(int columnIndex, InputStream x, int length) | void | Yes | +| updateBinaryStream(String columnLabel, InputStream x, int length) | void | Yes | +| updateBoolean(int columnIndex, boolean x) | void | Yes | +| updateBoolean(String columnLabel, boolean x) | void | Yes | +| updateByte(int columnIndex, byte x) | void | Yes | +| updateByte(String columnLabel, byte x) | void | Yes | +| updateBytes(int columnIndex, byte[] x) | void | Yes | +| updateBytes(String columnLabel, byte[] x) | void | Yes | +| updateCharacterStream(int columnIndex, Reader x, int length) | void | Yes | +| updateCharacterStream(String columnLabel, Reader reader, int length) | void | Yes | +| updateDate(int columnIndex, Date x) | void | Yes | +| updateDate(String columnLabel, Date x) | void | Yes | +| updateDouble(int columnIndex, double x) | void | Yes | +| updateDouble(String columnLabel, double x) | void | Yes | +| updateFloat(int columnIndex, float x) | void | Yes | +| updateFloat(String columnLabel, float x) | void | Yes | +| updateInt(int columnIndex, int x) | void | Yes | +| updateInt(String columnLabel, int x) | void | Yes | +| updateLong(int columnIndex, long x) | void | Yes | +| updateLong(String columnLabel, long x) | void | Yes | +| updateNull(int columnIndex) | void | Yes | +| updateNull(String columnLabel) | void | Yes | +| updateObject(int columnIndex, Object x) | void | Yes | +| updateObject(int columnIndex, Object x, int scaleOrLength) | void | Yes | +| updateObject(String columnLabel, Object x) | void | Yes | +| updateObject(String columnLabel, Object x, int scaleOrLength) | void | Yes | +| updateRow() | void | Yes | +| updateShort(int columnIndex, short x) | void | Yes | +| updateShort(String columnLabel, short x) | void | Yes | +| updateSQLXML(int columnIndex, SQLXML xmlObject) | void | Yes | +| updateSQLXML(String columnLabel, SQLXML xmlObject) | void | Yes | +| updateString(int columnIndex, String x) | void | Yes | +| updateString(String columnLabel, String x) | void | Yes | +| updateTime(int columnIndex, Time x) | void | Yes | +| updateTime(String columnLabel, Time x) | void | Yes | +| updateTimestamp(int columnIndex, Timestamp x) | void | Yes | +| updateTimestamp(String columnLabel, Timestamp x) | void | Yes | +| wasNull() | Boolean | Yes | + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 一个Statement不能有多个处于"open"状态的ResultSet。 +> - 用于遍历结果集(ResultSet)的游标(Cursor)在被提交后不能保持“open”的状态。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/7-java-sql-ResultSetMetaData.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/7-java-sql-ResultSetMetaData.md new file mode 100644 index 00000000..6894afc1 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/7-java-sql-ResultSetMetaData.md @@ -0,0 +1,43 @@ +--- +title: java.sql.ResultSetMetaData +summary: java.sql.ResultSetMetaData +author: Guo Huan +date: 2021-05-17 +--- + +# java.sql.ResultSetMetaData + +java.sql.ResultSetMetaData是对ResultSet对象相关信息的具体描述。 + +**表 1** 对java.sql.ResultSetMetaData的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :------------------------------- | :--------- | :--------- | +| getCatalogName(int column) | String | Yes | +| getColumnClassName(int column) | String | Yes | +| getColumnCount() | int | Yes | +| getColumnDisplaySize(int column) | int | Yes | +| getColumnLabel(int column) | String | Yes | +| getColumnName(int column) | String | Yes | +| getColumnType(int column) | int | Yes | +| getColumnTypeName(int column) | String | Yes | +| getPrecision(int column) | int | Yes | +| getScale(int column) | int | Yes | +| getSchemaName(int column) | String | Yes | +| getTableName(int column) | String | Yes | +| isAutoIncrement(int column) | boolean | Yes | +| isCaseSensitive(int column) | boolean | Yes | +| isCurrency(int column) | boolean | Yes | +| isDefinitelyWritable(int column) | boolean | Yes | +| isNullable(int column) | int | Yes | +| isReadOnly(int column) | boolean | Yes | +| isSearchable(int column) | boolean | Yes | +| isSigned(int column) | boolean | Yes | +| isWritable(int column) | boolean | Yes | + +> **说明**: +> +> uppercaseAttributeName为true时,下面接口会将查询结果转为大写,可转换范围为26个英文字母。 +> +> - public String getColumnName(int column) +> - public String getColumnLabel(int column) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/8-java-sql-Statement.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/8-java-sql-Statement.md new file mode 100644 index 00000000..0fe3fbb1 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/8-java-sql-Statement.md @@ -0,0 +1,69 @@ +--- +title: java.sql.Statement +summary: java.sql.Statement +author: Guo Huan +date: 2021-05-17 +--- + +# java.sql.Statement + +java.sql.Statement是SQL语句接口。 + +**表 1** 对java.sql.Statement的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :---------------------------------------------------- | :--------- | :--------- | +| addBatch(String sql) | void | Yes | +| clearBatch() | void | Yes | +| clearWarnings() | void | Yes | +| close() | void | Yes | +| closeOnCompletion() | void | Yes | +| execute(String sql) | Boolean | Yes | +| execute(String sql, int autoGeneratedKeys) | Boolean | Yes | +| execute(String sql, int[] columnIndexes) | Boolean | Yes | +| execute(String sql, String[] columnNames) | Boolean | Yes | +| executeBatch() | Boolean | Yes | +| executeQuery(String sql) | ResultSet | Yes | +| executeUpdate(String sql) | int | Yes | +| executeUpdate(String sql, int autoGeneratedKeys) | int | Yes | +| executeUpdate(String sql, int[] columnIndexes) | int | Yes | +| executeUpdate(String sql, String[] columnNames) | int | Yes | +| getConnection() | Connection | Yes | +| getFetchDirection() | int | Yes | +| getFetchSize() | int | Yes | +| getGeneratedKeys() | ResultSet | Yes | +| getMaxFieldSize() | int | Yes | +| getMaxRows() | int | Yes | +| getMoreResults() | boolean | Yes | +| getMoreResults(int current) | boolean | Yes | +| getResultSet() | ResultSet | Yes | +| getResultSetConcurrency() | int | Yes | +| getResultSetHoldability() | int | Yes | +| getResultSetType() | int | Yes | +| getQueryTimeout() | int | Yes | +| getUpdateCount() | int | Yes | +| getWarnings() | SQLWarning | Yes | +| isClosed() | Boolean | Yes | +| isCloseOnCompletion() | Boolean | Yes | +| isPoolable() | Boolean | Yes | +| setCursorName(String name) | void | Yes | +| setEscapeProcessing(boolean enable) | void | Yes | +| setFetchDirection(int direction) | void | Yes | +| setMaxFieldSize(int max) | void | Yes | +| setMaxRows(int max) | void | Yes | +| setPoolable(boolean poolable) | void | Yes | +| setQueryTimeout(int seconds) | void | Yes | +| setFetchSize(int rows) | void | Yes | +| cancel() | void | Yes | +| executeLargeUpdate(String sql) | long | No | +| getLargeUpdateCount() | long | No | +| executeLargeBatch() | long | No | +| executeLargeUpdate(String sql, int autoGeneratedKeys) | long | No | +| executeLargeUpdate(String sql, int[] columnIndexes) | long | No | +| executeLargeUpdate(String sql, String[] columnNames) | long | No | + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 通过setFetchSize可以减少结果集在客户端的内存占用情况。它的原理是通过将结果集打包成游标,然后分段处理,所以会加大数据库与客户端的通信量,会有性能损耗。 +> - 由于数据库游标是事务内有效,所以,在设置setFetchSize的同时,需要将连接设置为非自动提交模式,setAutoCommit(false)。同时在业务数据需要持久化到数据库中时,在连接上执行提交操作。 +> - LargeUpdate相关方法必须在JDBC4.2及以上使用。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/9-javax-sql-ConnectionPoolDataSource.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/9-javax-sql-ConnectionPoolDataSource.md new file mode 100644 index 00000000..731c5b7d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/15-JDBC/9-javax-sql-ConnectionPoolDataSource.md @@ -0,0 +1,17 @@ +--- +title: javax.sql.ConnectionPoolDataSource +summary: javax.sql.ConnectionPoolDataSource +author: Guo Huan +date: 2021-05-17 +--- + +# javax.sql.ConnectionPoolDataSource + +javax.sql.ConnectionPoolDataSource是数据源连接池接口。 + +**表 1** 对javax.sql.ConnectionPoolDataSource的支持情况 + +| 方法名 | 返回值类型 | 支持JDBC 4 | +| :----------------------------------------------- | :--------------- | :--------- | +| getPooledConnection() | PooledConnection | Yes | +| getPooledConnection(String user,String password) | PooledConnection | Yes | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/2-jdbc-package-driver-class-and-environment-class.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/2-jdbc-package-driver-class-and-environment-class.md new file mode 100644 index 00000000..c502ea5b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/2-jdbc-package-driver-class-and-environment-class.md @@ -0,0 +1,57 @@ +--- +title: JDBC包、驱动类和环境类 +summary: JDBC包、驱动类和环境类 +author: Guo Huan +date: 2021-04-26 +--- + +# JDBC包、驱动类和环境类 + +
+ +## JDBC包 + +在linux服务器端源代码目录下执行build.sh,获得驱动jar包postgresql.jar,包位置在源代码目录下。从发布包中获取, 包名为[openGauss-x.x.x-JDBC.tar.gz](https://opengauss.org/zh/download.html)。 + +驱动包与PostgreSQL保持兼容,其中类名、类结构与PostgreSQL驱动完全一致,曾经运行于PostgreSQL的应用程序可以直接移植到当前系统使用。 + +
+ +## 驱动类 + +在创建数据库连接之前,需要加载数据库驱动类"org.opengauss.Driver"。 + +> **说明:** +> +> - 由于MogDB在JDBC的使用上与PG的使用方法保持兼容,所以同时在同一个JVM虚拟机里加载PostgreSQL和openGauss的JDBC驱动包时,org.postgresql.Driver驱动类会冲突。 +> +> - 相比于PG驱动,openGauss JDBC驱动主要做了以下特性的增强: +> - 支持SHA256加密方式登录。 +> - 支持对接实现sf4j接口的第三方日志框架。 +> - 支持容灾切换。 + +
+ +## 环境类 + +客户端需配置JDK1.8,配置方法如下: + +1. DOS窗口输入"java -version",查看JDK版本,确认为JDK1.8版本。如果未安装JDK,请从官方网站下载安装包并安装。若系统环境JDK版本低于1.8,请参考[WebSphere配置MogDB数据源参考](../../../quick-start/mogdb-access/use-middleware-to-access-mogdb/websphere-configures-mogdb-data-source-reference.md)。 + +2. 根据如下步骤配置系统环境变量。 + + a. 右键单击"我的电脑",选择"属性"。 + + b. 在"系统"页面左侧导航栏单击"高级系统设置"。 + + c. 在"系统属性"页面,"高级"页签上单击"环境变量"。 + + d. 在"环境变量"页面上,"系统变量"区域单击"新建"或"编辑"配置系统变量。变量说明请参见表1。 + +**表 1** 变量说明 + +| 变量名 | 操作 | 变量值 | +| :-------- | :--------------- | :-------------------- | +| JAVA_HOME | - 若存在,则单击"编辑"。
- 若不存在,则单击"新建"。 | JAVA的安装目录。
例如: C:\\Program Files\\Java\\jdk1.8.0_131 | +| Path | 编辑 | - 若配置了JAVA_HOME,则在变量值的最前面加上: %JAVA_HOME%\\bin;
- 若未配置JAVA_HOME,则在变量值的最前面加上 JAVA安装的全路径:
C:\\Program Files\\Java\\jdk1.8.0_131\\bin; | +| CLASSPATH | 新建 | ".;%JAVA_HOME%\\lib;%JAVA_HOME%\\lib\\tools.jar;" | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/3-development-process.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/3-development-process.md new file mode 100644 index 00000000..37785461 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/3-development-process.md @@ -0,0 +1,12 @@ +--- +title: 开发流程 +summary: 开发流程 +author: Guo Huan +date: 2021-04-26 +--- + +# 开发流程 + +**图 1** 采用JDBC开发应用程序的流程 + +![采用JDBC开发应用程序的流程](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/development-process-1.png) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/4-loading-the-driver.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/4-loading-the-driver.md new file mode 100644 index 00000000..cc230090 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/4-loading-the-driver.md @@ -0,0 +1,19 @@ +--- +title: 加载驱动 +summary: 加载驱动 +author: Guo Huan +date: 2021-04-26 +--- + +# 加载驱动 + +在创建数据库连接之前,需要先加载数据库驱动程序。 + +加载驱动有两种方法: + +- 在代码中创建连接之前任意位置隐含装载: Class.forName("org.opengauss.Driver"); + +- 在JVM启动时参数传递: java -Djdbc.drivers=org.opengauss.Driver jdbctest + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > 上述jdbctest为测试用例程序的名称。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/5-connecting-to-a-database.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/5-connecting-to-a-database.md new file mode 100644 index 00000000..a2d0e64b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/5-connecting-to-a-database.md @@ -0,0 +1,111 @@ +--- +title: 连接数据库 +summary: 连接数据库 +author: Guo Huan +date: 2021-04-26 +--- + +# 连接数据库 + +在创建数据库连接之后,才能使用它来执行SQL语句操作数据。 + +
+ +## 函数原型 + +JDBC提供了三个方法,用于创建数据库连接。 + +- DriverManager.getConnection(String url); +- DriverManager.getConnection(String url, Properties info); +- DriverManager.getConnection(String url, String user, String password); + +
+ +## 参数 + +**表 1** 数据库连接参数 + +| 参数 | 描述 | +| :------- | :-------------- | +| url | opengauss.jar数据库连接描述符。格式如下:
- `jdbc:opengauss:database`
- `jdbc:opengauss://host/database`
- `jdbc:opengauss://host:port/database`
- `jdbc:opengauss://host:port/database?param1=value1¶m2=value2`
-`jdbc:opengauss://host1:port1,host2:port2/database?param1=value1¶m2=value2`
说明:
- database为要连接的数据库名称。
- host为数据库服务器名称或IP地址。
连接MogDB的机器与MogDB不在同一网段时,host指定的IP地址应为Manager界面上所设的coo.cooListenIp2(应用访问IP)的取值。
由于安全原因,数据库主节点禁止MogDB内部其他节点无认证接入。如果要在MogDB内部访问数据库主节点,请将JDBC程序部署在数据库主节点所在机器,host使用"127.0.0.1"。否则可能会出现"FATAL: Forbid remote connection with trust method!"错误。
建议业务系统单独部署在MogDB外部,否则可能会影响数据库运行性能。
缺省情况下,连接服务器为localhost。
- port为数据库服务器端口。
缺省情况下,会尝试连接到5431端口的database。
- param为参数名称,即数据库连接属性。
参数可以配置在URL中,以"?"开始配置,以"="给参数赋值,以"&"作为不同参数的间隔。也可以采用info对象的属性方式进行配置,详细示例会在本节给出。
- value为参数值,即数据库连接属性值。
- 连接时需配置connectTimeout、socketTimeout,如果未配置,默认为0,即不会超时。在DN与客户端出现网络故障时,客户端一直未收到DN侧ACK确认报文,会启动超时重传机制,不断的进行重传。当超时时间达到系统默认的600s后才会报超时错误,这也就会导致RTO时间很高。 | +| info | 数据库连接属性(所有属性大小写敏感)。常用的属性如下:
- PGDBNAME: String类型。表示数据库名称。(URL中无需配置该参数,自动从URL中解析)
- PGHOST: String类型。主机IP地址。详细示例见下。
- PGPORT: Integer类型。主机端口号。详细示例见下。
- user: String类型。表示创建连接的数据库用户。
- password: String类型。表示数据库用户的密码。
- enable_ce:String类型。其中enable_ce=1表示JDBC支持密态等值查询。
- loggerLevel: String类型。目前支持3种级别: OFF、DEBUG、TRACE。设置为OFF关闭日志,设置为DEBUG和TRACE记录的日志信息详细程度不同。
- loggerFile: String类型。Logger输出的文件名。需要显示指定日志文件名,若未指定目录则生成在客户端运行程序目录。
- allowEncodingChanges: Boolean类型。设置该参数值为"true"进行字符集类型更改,配合characterEncoding=CHARSET设置字符集,二者使用"&"分隔。
- currentSchema: String类型。在search-path中指定要设置的schema。
- hostRecheckSeconds: Integer类型。JDBC尝试连接主机后会保存主机状态: 连接成功或连接失败。在hostRecheckSeconds时间内保持可信,超过则状态失效。缺省值是10秒。
- ssl: Boolean类型。以SSL方式连接。
ssl=true可支持NonValidatingFactory通道和使用证书的方式:
1、NonValidatingFactory通道需要配置用户名和密码,同时将SSL设置为true。
2、配置客户端证书、密钥、根证书,将SSL设置为true。
- sslmode: String类型。SSL认证方式。取值范围为: require、verify-ca、verify-full。
- require只尝试SSL连接,如果存在CA文件,则应设置成verify-ca的方式验证。
- verify-ca只尝试SSL连接,并且验证服务器是否具有由可信任的证书机构签发的证书。
- verify-full只尝试SSL连接,并且验证服务器是否具有由可信任的证书机构签发的证书,以及验证服务器主机名是否与证书中的一致。
- sslcert: String类型。提供证书文件的完整路径。客户端和服务端证书的类型为End Entity。
- sslkey: String类型。提供密钥文件的完整路径。使用时将客户端证书转换为DER格式:
`openssl pkcs8 -topk8 -outform DER -in client.key -out client.key.pk8 -nocrypt`
- sslrootcert: String类型。SSL根证书的文件名。根证书的类型为CA。
- sslpassword: String类型。提供给ConsoleCallbackHandler使用。
- sslpasswordcallback: String类型。SSL密码提供者的类名。缺省值: org.opengauss.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler。
- sslfactory: String类型。提供的值是SSLSocketFactory在建立SSL连接时用的类名。
- sslfactoryarg: String类型。此值是上面提供的sslfactory类的构造函数的可选参数(不推荐使用)。
- sslhostnameverifier: String类型。主机名验证程序的类名。接口实现javax.net.ssl.HostnameVerifier,默认使用org.opengauss.ssl.PGjdbcHostnameVerifier。
- loginTimeout: Integer类型。指建立数据库连接的等待时间。超时时间单位为秒。
- connectTimeout: Integer类型。用于连接服务器操作的超时值。如果连接到服务器花费的时间超过此值,则连接断开。超时时间单位为秒,值为0时表示已禁用,timeout不发生。
- socketTimeout: Integer类型。用于socket读取操作的超时值。如果从服务器读取所花费的时间超过此值,则连接关闭。超时时间单位为秒,值为0时表示已禁用,timeout不发生。
- cancelSignalTimeout: Integer类型。发送取消消息本身可能会阻塞,此属性控制用于取消命令的"connect超时"和"socket超时"。超时时间单位为秒,默认值为10秒。
- tcpKeepAlive: Boolean类型。启用或禁用TCP保活探测功能。默认为false。
- logUnclosedConnections: Boolean类型。客户端可能由于未调用Connection对象的close()方法而泄漏Connection对象。最终这些对象将被垃圾回收,并且调用finalize()方法。如果调用者自己忽略了此操作,该方法将关闭Connection。
- assumeMinServerVersion: String类型。客户端会发送请求进行float精度设置。该参数设置要连接的服务器版本,如assumeMinServerVersion=9.0,可以在建立时减少相关包的发送。
- ApplicationName: String类型。设置正在使用连接的JDBC驱动的名称。通过在数据库主节点上查询pg_stat_activity表可以看到正在连接的客户端信息,JDBC驱动名称显示在application_name列。缺省值为PostgreSQL JDBC Driver。
- connectionExtraInfo: Boolean类型。表示驱动是否上报当前驱动的部署路径、进程属主用户到数据库。取值范围: true或false,默认值为false。设置connectionExtraInfo为true,JDBC驱动会将当前驱动的部署路径、进程属主用户上报到数据库中,记录在connection_info参数里;同时可以在PG_STAT_ACTIVITY中查询到。
- autosave: String类型。共有3种: "always", "never", "conservative"。如果查询失败,指定驱动程序应该执行的操作。在autosave=always模式下,JDBC驱动程序在每次查询之前设置一个保存点,并在失败时回滚到该保存点。在autosave=never模式(默认)下,无保存点。在autosave=conservative模式下,每次查询都会设置保存点,但是只会在"statement XXX无效"等情况下回滚并重试。
- protocolVersion: Integer类型。连接协议版本号,目前仅支持3。注意:设置该参数时将采用md5加密方式,需要同步修改数据库的加密方式:gs_guc set -N all -I all -c "password_encryption_type=1" ,重启MogDB生效后需要创建用md5方式加密口令的用户。同时修改pg_hba.conf,将客户端连接方式修改为md5。用新建用户进行登录(不推荐)。
说明:
MD5加密算法安全性低,存在安全风险,建议使用更安全的加密算法。
- prepareThreshold: Integer类型。控制parse语句何时发送。默认值是5。第一次parse一个SQL比较慢,后面再parse就会比较快,因为有缓存了。如果一个会话连续多次执行同一个SQL,在达到prepareThreshold次数以上时,JDBC将不再对这个SQL发送parse命令。
- preparedStatementCacheQueries: Integer类型。确定每个连接中缓存的查询数,默认情况下是256。若在prepareStatement()调用中使用超过256个不同的查询,则最近最少使用的查询缓存将被丢弃。0表示禁用缓存。
- preparedStatementCacheSizeMiB: Integer类型。确定每个连接可缓存的最大值(以兆字节为单位),默认情况下是5。若缓存了超过5MB的查询,则最近最少使用的查询缓存将被丢弃。0表示禁用缓存。
- databaseMetadataCacheFields: Integer类型。默认值是65536。指定每个连接可缓存的最大值。"0"表示禁用缓存。
- databaseMetadataCacheFieldsMiB: Integer类型。默认值是5。每个连接可缓存的最大值,单位是MB。"0"表示禁用缓存。
- stringtype: String类型,可选字段为: false, "unspecified", "varchar"。设置通过setString()方法使用的PreparedStatement参数的类型,如果stringtype设置为VARCHAR(默认值),则这些参数将作为varchar参数发送给服务器。若stringtype设置为unspecified,则参数将作为untyped值发送到服务器,服务器将尝试推断适当的类型。
- batchMode: Boolean类型。用于确定是否使用batch模式连接。默认值为on,表示开启batch模式。
- fetchsize: Integer类型。用于设置数据库连接所创建statement的默认fetchsize。默认值为0,表示一次获取所有结果。
- reWriteBatchedInserts: Boolean类型。批量导入时,该参数设置为on,可将N条插入语句合并为一条: insert into TABLE_NAME values(values1, …, valuesN), …, (values1, …, valuesN);使用该参数时,需设置batchMode=off。
- unknownLength: Integer类型,默认为Integer.MAX_VALUE。某些postgresql类型(例如TEXT)没有明确定义的长度,当通过ResultSetMetaData.getColumnDisplaySize和ResultSetMetaData.getPrecision等函数返回关于这些类型的数据时,此参数指定未知长度类型的长度。
- defaultRowFetchSize: Integer类型。确定一次fetch在ResultSet中读取的行数。限制每次访问数据库时读取的行数可以避免不必要的内存消耗,从而避免OutOfMemoryException。缺省值是0,这意味着ResultSet中将一次获取所有行。没有负数。
- binaryTransfer: Boolean类型。使用二进制格式发送和接收数据,默认值为"false"。
- binaryTransferEnable: String类型。启用二进制传输的类型列表,以逗号分隔。OID编号和名称二选一,例如binaryTransferEnable=Integer4_ARRAY,Integer8_ARRAY。比如:OID名称为BLOB,编号为88,可以如下配置:
binaryTransferEnable=BLOB 或 binaryTransferEnable=88
- binaryTransferDisEnable: String类型。禁用二进制传输的类型列表,以逗号分隔。OID编号和名称二选一。覆盖binaryTransferEnable的设置。
- blobMode: String类型。用于设置setBinaryStream方法为不同类型的数据赋值,设置为on时表示为blob类型数据赋值,设置为off时表示为bytea类型数据赋值,默认为on。
- socketFactory: String类型。用于创建与服务器socket连接的类的名称。该类必须实现了接口"javax.net.SocketFactory",并定义无参或单String参数的构造函数。
- socketFactoryArg: String类型。此值是上面提供的socketFactory类的构造函数的可选参数,不推荐使用。
- receiveBufferSize: Integer类型。该值用于设置连接流上的SO_RCVBUF。
- sendBufferSize: Integer类型。该值用于设置连接流上的SO_SNDBUF。
- preferQueryMode: String类型。共有4种: "extended", "extendedForPrepared", "extendedCacheEverything", "simple"。用于指定执行查询的模式,simple模式会excute,不parse和bind;extended模式会bind和excute;extendedForPrepared模式为prepared statement扩展使用;extendedCacheEverything模式会缓存每个statement。
- targetServerType: String类型。该参数识别主备数据节点是通过查询URL连接串中,数据节点是否允许写操作来实现的,默认为“any”。共有四种:“any”、“master”、“slave”、“preferSlave”:
1. master则尝试连接到URL连接串中的主节点,如果找不到就抛出异常。
2. slave则尝试连接到URL连接串中的备节点,如果找不到就抛出异常。
3. preferSlave则尝试连接到URL连接串中的备数据节点(如果有可用的话),否则连接到主数据节点。
4. any则尝试连接URL连接串中的任何一个数据节点。
- priorityServers:Integer类型。此值用于指定url上配置的前n个节点作为主集群被优先连接。默认值为null。该值为数字,大于0,且小于url上配置的DN数量。例如:`jdbc:opengauss://host1:port1,host2:port2,host3:port3,host4:port4,/database?priorityServers=2`。即表示host1与host2为主集群节点,host3与host4为容灾集群节点。
- forceTargetServerSlave:Boolean类型。此值用于控制是否开启强制连接备机功能,并在集群发生主备切换时,禁止已存在的连接在升主备机上继续使用。默认值为false,表示不开启强制连接备机功能。true,表示开启强制连接备机功能。 | +| user | 数据库用户。 | +| password | 数据库用户的密码。 | + +
+ +## 示例 + +```java +//以下代码将获取数据库连接操作封装为一个接口,可通过给定用户名和密码来连接数据库。 +public static Connection getConnect(String username, String passwd) + { + //驱动类。 + String driver = "org.opengauss.Driver"; + //数据库连接描述符。 + String sourceURL = "jdbc:opengauss://10.10.0.13:8000/postgres"; + Connection conn = null; + + try + { + //加载驱动。 + Class.forName(driver); + } + catch( Exception e ) + { + e.printStackTrace(); + return null; + } + + try + { + //创建连接。 + conn = DriverManager.getConnection(sourceURL, username, passwd); + System.out.println("Connection succeed!"); + } + catch(Exception e) + { + e.printStackTrace(); + return null; + } + + return conn; + }; +// 以下代码将使用Properties对象作为参数建立连接 +public static Connection getConnectUseProp(String username, String passwd) + { + //驱动类。 + String driver = "org.opengauss.Driver"; + //数据库连接描述符。 + String sourceURL = "jdbc:opengauss://10.10.0.13:8000/postgres?"; + Connection conn = null; + Properties info = new Properties(); + + try + { + //加载驱动。 + Class.forName(driver); + } + catch( Exception e ) + { + e.printStackTrace(); + return null; + } + + try + { + info.setProperty("user", username); + info.setProperty("password", passwd); + //创建连接。 + conn = DriverManager.getConnection(sourceURL, info); + System.out.println("Connection succeed!"); + } + catch(Exception e) + { + e.printStackTrace(); + return null; + } + + return conn; + }; +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/6-connecting-to-a-database-using-ssl.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/6-connecting-to-a-database-using-ssl.md new file mode 100644 index 00000000..682f9b71 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/6-connecting-to-a-database-using-ssl.md @@ -0,0 +1,152 @@ +--- +title: 连接数据库(以SSL方式) +summary: 连接数据库(以SSL方式) +author: Guo Huan +date: 2021-04-26 +--- + +# 连接数据库(以SSL方式) + +用户通过JDBC连接MogDB服务器时,可以通过开启SSL加密客户端和服务器之间的通讯,为敏感数据在Internet上的传输提供了一种安全保障手段。本小节主要介绍应用程序通过JDBC如何采用SSL的方式连接MogDB。在使用本小节所描述的方法前,默认用户已经获取了服务端和客户端所需要的证书和私钥文件,关于证书等文件的获取请参考Openssl相关文档和命令 。 + +
+ +## 服务端配置 + +当开启SSL模式后,必须提供根证书、服务器证书和私钥。 + +配置步骤(假设用户的证书文件放在数据目录/mogdb/data/datanode下,且采用默认文件名): + +1. 以操作系统用户omm登录数据库主节点。 + +2. 生成并配置证书 + + 生成SSL证书,具体请参见[证书生成](../../../security-guide/security/1-client-access-authentication.md#证书生成)。将生成出的文件server.crt,server.key,cacert.pem拷贝到服务端数据目录下。 + + 使用如下命令可以查询数据库节点的数据目录,instance列为数据目录。 + + ```bash + gs_om -t status --detail + ``` + + 在Unix系统上,server.crt、server.key的权限设置必须禁止任何外部或组的访问,请执行如下命令实现这一点。 + + ```bash + chmod 0600 server.key + ``` + +3. 开启SSL认证模式。 + + ```bash + gs_guc set -D /mogdb/data/datanode -c "ssl=on" + ``` + +4. 配置客户端接入认证参数,IP为所要连接的主机IP。 + + ```bash + gs_guc reload -D /mogdb/data/datanode -h "hostssl all all 127.0.0.1/32 cert" + gs_guc reload -D /mogdb/data/datanode -h "hostssl all all IP/32 cert" + ``` + + 表示允许127.0.0.1/32网段的客户端以ssl认证方式连接到MogDB服务器。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知:** + > + > - 如果服务端pg_hba.conf文件中METHOD配置为cert,则只有客户端使用证书(client.crt)中所设置的用户名(common name)才能够成功连接数据库。如果设置为md5或sha256则对连接数据库的用户没有限制。 + > - MD5加密算法安全性低,存在安全风险,建议使用更安全的加密算法。 + +5. 配置SSL认证相关的数字证书参数。 + + 各命令后所附为设置成功的回显。 + + ```bash + gs_guc set -D /mogdb/data/datanode -c "ssl_cert_file='server.crt'" + gs_guc set: ssl_cert_file='server.crt' + ``` + + ```bash + gs_guc set -D /mogdb/data/datanode -c "ssl_key_file='server.key'" + gs_guc set: ssl_key_file='server.key' + ``` + + ```bash + gs_guc set -D /mogdb/data/datanode -c "ssl_ca_file='cacert.pem'" + gs_guc set: ssl_ca_file='cacert.pem' + ``` + +6. 重启数据库。 + + ```bash + gs_om -t stop && gs_om -t start + ``` + +
+ +## 客户端配置 + +配置步骤如下: + +上传证书文件,将在服务端配置章节生成出的文件client.key.pk8,client.crt,cacert.pem放置在客户端。 + +
+ +## 示例 + +注:示例1和示例2选择其一。 + +```java +public class SSL{ + public static void main(String[] args) { + Properties urlProps = new Properties(); + String urls = "jdbc:opengauss://10.29.37.136:8000/postgres"; + + /** + * ================== 示例1 使用NonValidatingFactory通道 + */ + urlProps.setProperty("sslfactory","org.opengauss.ssl.NonValidatingFactory"); + urlProps.setProperty("user", "world"); + urlProps.setProperty("password", "test@123"); + urlProps.setProperty("ssl", "true"); + /** + * ================== 示例2 使用证书 + */ + urlProps.setProperty("sslcert", "client.crt"); + urlProps.setProperty("sslkey", "client.key.pk8"); + urlProps.setProperty("sslrootcert", "cacert.pem"); + urlProps.setProperty("user", "world"); + urlProps.setProperty("ssl", "true"); + /* sslmode可配置为:require、verify-ca、verify-full,以下三个示例选择其一*/ + /* ================== 示例2.1 设置sslmode为require,使用证书 */ + urlProps.setProperty("sslmode", "require"); + /* ================== 示例2.2 设置sslmode为verify-ca,使用证书 */ + urlProps.setProperty("sslmode", "verify-ca"); + /* ================== 示例2.3 设置sslmode为verify-full,使用证书(Linux下验证) */ + urls = "jdbc:opengauss://world:8000/postgres"; + urlProps.setProperty("sslmode", "verify-full"); + try { + Class.forName("org.opengauss.Driver").newInstance(); + } catch (Exception e) { + e.printStackTrace(); + } + try { + Connection conn; + conn = DriverManager.getConnection(urls,urlProps); + conn.close(); + } catch (Exception e) { + e.printStackTrace(); + } + } +} +/** + * 注:将客户端密钥转化为DER格式: + * openssl pkcs8 -topk8 -outform DER -in client.key -out client.key.pk8 -nocrypt + * openssl pkcs8 -topk8 -inform PEM -in client.key -outform DER -out client.key.der -v1 PBE-MD5-DES + * openssl pkcs8 -topk8 -inform PEM -in client.key -outform DER -out client.key.der -v1 PBE-SHA1-3DES + * 以上算法由于安全级别较低,不推荐使用。 + * 如果客户需要采用更高级别的私钥加密算法,启用bouncycastle或者其他第三方私钥解密密码包后可以使用的私钥加密算法如下: + * openssl pkcs8 -in client.key -topk8 -outform DER -out client.key.der -v2 AES128 + * openssl pkcs8 -in client.key -topk8 -outform DER -out client.key.der -v2 aes-256-cbc -iter 1000000 + * openssl pkcs8 -in client.key -topk8 -out client.key.der -outform Der -v2 aes-256-cbc -v2prf hmacWithSHA512 + * 启用bouncycastle:使用jdbc的项目引入依赖:bcpkix-jdk15on.jar包,版本建议:1.65以上。 + */ +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/7-running-sql-statements.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/7-running-sql-statements.md new file mode 100644 index 00000000..1e41522a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/7-running-sql-statements.md @@ -0,0 +1,256 @@ +--- +title: 执行SQL语句 +summary: 执行SQL语句 +author: Guo Huan +date: 2021-06-07 +--- + +# 执行SQL语句 + +
+ +## 执行普通SQL语句 + +应用程序通过执行SQL语句来操作数据库的数据(不用传递参数的语句),需要按以下步骤执行: + +1. 调用Connection的createStatement方法创建语句对象。 + + ```java + Connection conn = DriverManager.getConnection("url","user","password"); + Statement stmt = conn.createStatement(); + ``` + +2. 调用Statement的executeUpdate方法执行SQL语句。 + + ```java + int rc = stmt.executeUpdate("CREATE TABLE customer_t1(c_customer_sk INTEGER, c_customer_name VARCHAR(32));"); + ``` + + > **说明:** + > + > - 数据库中收到的一次执行请求(不在事务块中),如果含有多条语句,将会被打包成一个事务,事务块中不支持vacuum操作。如果其中有一个语句失败,那么整个请求都将会被回滚。 + > - 使用Statement执行多语句时应以“;”作为各语句间的分隔符,存储过程、函数、匿名块不支持多语句执行。 + > - “/”可用作创建单个存储过程、函数、匿名块的结束符。 + +3. 关闭语句对象。 + + ```java + stmt.close(); + ``` + +
+ +## 执行预编译SQL语句 + +预编译语句是只编译和优化一次,然后可以通过设置不同的参数值多次使用。由于已经预先编译好,后续使用会减少执行时间。因此,如果多次执行一条语句,请选择使用预编译语句。可以按以下步骤执行: + +1. 调用Connection的prepareStatement方法创建预编译语句对象。 + + ```java + PreparedStatement pstmt = con.prepareStatement("UPDATE customer_t1 SET c_customer_name = ? WHERE c_customer_sk = 1"); + ``` + +2. 调用PreparedStatement的setShort设置参数。 + + ```java + pstmt.setShort(1, (short)2); + ``` + +3. 调用PreparedStatement的executeUpdate方法执行预编译SQL语句。 + + ```java + int rowcount = pstmt.executeUpdate(); + ``` + +4. 调用PreparedStatement的close方法关闭预编译语句对象。 + + ```java + pstmt.close(); + ``` + +
+ +## 调用存储过程 + +MogDB支持通过JDBC直接调用事先创建的存储过程,步骤如下: + +1. 调用Connection的prepareCall方法创建调用语句对象。 + + ```java + Connection myConn = DriverManager.getConnection("url","user","password"); + CallableStatement cstmt = myConn.prepareCall("{? = CALL TESTPROC(?,?,?)}"); + ``` + +2. 调用CallableStatement的setInt方法设置参数。 + + ```java + cstmt.setInt(2, 50); + cstmt.setInt(1, 20); + cstmt.setInt(3, 90); + ``` + +3. 调用CallableStatement的registerOutParameter方法注册输出参数。 + + ```java + cstmt.registerOutParameter(4, Types.INTEGER); //注册out类型的参数,类型为整型。 + ``` + +4. 调用CallableStatement的execute执行方法调用。 + + ```java + cstmt.execute(); + ``` + +5. 调用CallableStatement的getInt方法获取输出参数。 + + ```java + int out = cstmt.getInt(4); //获取out参数 + ``` + + 示例: + + ```sql + //在数据库中已创建了如下存储过程,它带有out参数。 + create or replace procedure testproc + ( + psv_in1 in integer, + psv_in2 in integer, + psv_inout in out integer + ) + as + begin + psv_inout := psv_in1 + psv_in2 + psv_inout; + end; + / + ``` + +6. 调用CallableStatement的close方法关闭调用语句。 + + ```java + cstmt.close(); + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > + > - 很多的数据库类如Connection、Statement和ResultSet都有close()方法,在使用完对象后应把它们关闭。要注意的是,Connection的关闭将间接关闭所有与它关联的 Statement,Statement的关闭间接关闭了ResultSet。 + > + > - 一些JDBC驱动程序还提供命名参数的方法来设置参数。命名参数的方法允许根据名称而不是顺序来设置参数,若参数有默认值,则可以不用指定参数值就可以使用此参数的默认值。即使存储过程中参数的顺序发生了变更,也不必修改应用程序。目前MogDB数据库的JDBC驱动程序不支持此方法。 + > + > - MogDB数据库不支持带有输出参数的函数,也不支持存储过程和函数参数默认值。 + > + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: + > + > - 当游标作为存储过程的返回值时,如果使用JDBC调用该存储过程,返回的游标将不可用。 + > + > - 存储过程不能和普通SQL在同一条语句中执行。 + > + > - 存储过程中inout类型参数必需注册出参。 + +
+ +## Oracle兼容模式启用重载时,调用存储过程 + +打开参数behavior_compat_options='proc_outparam_override'后,JDBC调用事先创建的存储过程,步骤如下: + +1. 调用Connection的prepareCall方法创建调用语句对象。 + + ``` + Connection conn = DriverManager.getConnection("url","user","password"); + CallableStatement cs = conn.prepareCall("{ CALL TEST_PROC(?,?,?) }"); + ``` + +2. 调用CallableStatement的setInt方法设置参数。 + + ``` + PGobject pGobject = new PGobject(); + pGobject.setType("public.compfoo"); // 设置复合类型名,格式为“schema.typename”。 + pGobject.setValue("(1,demo)"); // 绑定复合类型值,格式为“(value1,value2)”。 + cs.setObject(1, pGobject); + ``` + +3. 调用CallableStatement的registerOutParameter方法注册输出参数。 + + ``` + // 注册out类型的参数,类型为复合类型,格式为“schema.typename”。 + cs.registerOutParameter(2, Types.STRUCT, "public.compfoo"); + ``` + +4. 调用CallableStatement的execute执行方法调用。 + + ``` + cs.execute(); + ``` + +5. 调用CallableStatement的getObject方法获取输出参数。 + + ``` + PGobject result = (PGobject)cs.getObject(2); // 获取out参数 + result.getValue(); // 获取复合类型字符串形式值。 + result.getArrayValue(); //获取复合类型数组形式值,以复合数据类型字段顺序排序。 + result.getStruct(); //获取复合类型子类型名,按创建顺序排序。 + ``` + +6. 调用CallableStatement的close方法关闭调用语句。 + + ``` + cs.close(); + ``` + + > **说明**: + > + > - oracle兼容模式开启参数后,调用存储过程必须使用{call proc_name(?,?,?)}形式调用,调用函数必须使用{? = call func_name(?,?)}形式调用(等号左侧的“?”为函数返回值的占位符,用于注册函数返回值)。 + > - 参数behavior_compat_options='proc_outparam_override'行为变更后,业务需要重新建立连接,否则无法正确调用存储过程和函数。 + > - 函数和存储过程中包含复合类型时,参数的绑定与注册需要使用schema.typename形式。 + +示例: + +``` +// 在数据库创建复合数据类型。 +CREATE TYPE compfoo AS (f1 int, f3 text); +// 在数据库中已创建了如下存储过程,它带有out参数。 +create or replace procedure test_proc +( + psv_in in compfoo, + psv_out out compfoo +) +as +begin + psv_out := psv_in; +end; +/ +``` + +
+ +## 执行批处理 + +用一条预处理语句处理多条相似的数据,数据库只创建一次执行计划,节省了语句的编译和优化时间。可以按如下步骤执行: + +1. 调用Connection的prepareStatement方法创建预编译语句对象。 + + ```java + Connection conn = DriverManager.getConnection("url","user","password"); + PreparedStatement pstmt = conn.prepareStatement("INSERT INTO customer_t1 VALUES (?)"); + ``` + +2. 针对每条数据都要调用setShort设置参数,以及调用addBatch确认该条设置完毕。 + + ```java + pstmt.setShort(1, (short)2); + pstmt.addBatch(); + ``` + +3. 调用PreparedStatement的executeBatch方法执行批处理。 + + ```java + int[] rowcount = pstmt.executeBatch(); + ``` + +4. 调用PreparedStatement的close方法关闭预编译语句对象。 + + ```java + pstmt.close(); + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > 在实际的批处理过程中,通常不终止批处理程序的执行,否则会降低数据库的性能。因此在批处理程序时,应该关闭自动提交功能,每几行提交一次。关闭自动提交功能的语句为: conn.setAutoCommit(false); diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/8-processing-data-in-a-result-set.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/8-processing-data-in-a-result-set.md new file mode 100644 index 00000000..b578d2f0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/8-processing-data-in-a-result-set.md @@ -0,0 +1,84 @@ +--- +title: 处理结果集 +summary: 处理结果集 +author: Guo Huan +date: 2021-04-26 +--- + +# 处理结果集 + +
+ +## 设置结果集类型 + +不同类型的结果集有各自的应用场景,应用程序需要根据实际情况选择相应的结果集类型。在执行SQL语句过程中,都需要先创建相应的语句对象,而部分创建语句对象的方法提供了设置结果集类型的功能。具体的参数设置如[表1](#结果集类型)所示。涉及的Connection的方法如下: + +``` +//创建一个Statement对象,该对象将生成具有给定类型和并发性的ResultSet对象。 +createStatement(int resultSetType, int resultSetConcurrency); + +//创建一个PreparedStatement对象,该对象将生成具有给定类型和并发性的ResultSet对象。 +prepareStatement(String sql, int resultSetType, int resultSetConcurrency); + +//创建一个CallableStatement对象,该对象将生成具有给定类型和并发性的ResultSet对象。 +prepareCall(String sql, int resultSetType, int resultSetConcurrency); +``` + +**表 1** 结果集类型 + +| 参数 | 描述 | +| :------------------- | :-------------------------| +| resultSetType | 表示结果集的类型,具体有三种类型:
- ResultSet.TYPE_FORWARD_ONLY:ResultSet只能向前移动。是缺省值。
- ResultSet.TYPE_SCROLL_SENSITIVE:在修改后重新滚动到修改所在行,可以看到修改后的结果。
- ResultSet.TYPE_SCROLL_INSENSITIVE:对可修改例程所做的编辑不进行显示。
说明:
结果集从数据库中读取了数据之后,即使类型是ResultSet.TYPE_SCROLL_SENSITIVE,也不会看到由其他事务在这之后引起的改变。调用ResultSet的refreshRow()方法,可进入数据库并从其中取得当前游标所指记录的最新数据。 | +| resultSetConcurrency | 表示结果集的并发,具体有两种类型:
- ResultSet.CONCUR_READ_ONLY: 如果不从结果集中的数据建立一个新的更新语句,不能对结果集中的数据进行更新。
- ResultSet.CONCUR_UPDATEABLE: 可改变的结果集。对于可滚动的结果集,可对结果集进行适当的改变。 | + +
+ +## 在结果集中定位 + +ResultSet对象具有指向其当前数据行的光标。最初,光标被置于第一行之前。next方法将光标移动到下一行;因为该方法在ResultSet对象没有下一行时返回false,所以可以在while循环中使用它来迭代结果集。但对于可滚动的结果集,JDBC驱动程序提供更多的定位方法,使ResultSet指向特定的行。定位方法如[表2](#结果集中定位方法)所示。 + +**表 2** 在结果集中定位的方法 + +| 方法 | 描述 | +| :------------ | :----------------------------------------------------------------------------------------------- | +| next() | 把ResultSet向下移动一行。 | +| previous() | 把ResultSet向上移动一行。 | +| beforeFirst() | 把ResultSet定位到第一行之前。 | +| afterLast() | 把ResultSet定位到最后一行之后。 | +| first() | 把ResultSet定位到第一行。 | +| last() | 把ResultSet定位到最后一行。 | +| absolute(int) | 把ResultSet移动到参数指定的行数。 | +| relative(int) | 通过设置为1向前(设置为1,相当于next())或者向后(设置为-1,相当于previous())移动参数指定的行。 | + +
+ +## 获取结果集中光标的位置 + +对于可滚动的结果集,可能会调用定位方法来改变光标的位置。JDBC驱动程序提供了获取结果集中光标所处位置的方法。获取光标位置的方法如[表3](#获取结果集光标位置)所示。 + +**表 3 ** 获取结果集光标的位置 + +| 方法 | 描述 | +| :-------------- | :------------------- | +| isFirst() | 是否在一行。 | +| isLast() | 是否在最后一行。 | +| isBeforeFirst() | 是否在第一行之前。 | +| isAfterLast() | 是否在最后一行之后。 | +| getRow() | 获取当前在第几行。 | + +
+ +## 获取结果集中的数据 + +ResultSet对象提供了丰富的方法,以获取结果集中的数据。获取数据常用的方法如[表4](#对象的常用方法)所示,其他方法请参考JDK官方文档。 + +**表 4** ResultSet对象的常用方法 + +| 方法 | 描述 | +| :----------------------------------- | :----------------------- | +| int getInt(int columnIndex) | 按列标获取int型数据。 | +| int getInt(String columnLabel) | 按列名获取int型数据。 | +| String getString(int columnIndex) | 按列标获取String型数据。 | +| String getString(String columnLabel) | 按列名获取String型数据。 | +| Date getDate(int columnIndex) | 按列标获取Date型数据 | +| Date getDate(String columnLabel) | 按列名获取Date型数据。 | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/8.1-log-management.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/8.1-log-management.md new file mode 100644 index 00000000..75611108 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/8.1-log-management.md @@ -0,0 +1,231 @@ +--- +title: 日志管理 +summary: 日志管理 +author: Zhang Cuiping +date: 2022-04-23 +--- + +# 日志管理 + +MogDB JDBC驱动程序支持使用日志记录来帮助解决在应用程序中使用MogDB JDBC驱动程序时的问题。MogDB JDBC支持如下两种日志管理方式: + +1. 对接应用程序使用的SLF4J日志框架。 +2. 对接应用程序使用的JdkLogger日志框架。 + +SLF4J和JdkLogger是业界Java应用程序日志管理的主流框架,描述应用程序如何使用这些框架超出了本文范围,用户请参考对应的官方文档 + +- SLF4J: +- JdkLogger + +方式一:对接应用程序的SLF4J日志框架。 + +在建立连接时,url配置logger=Slf4JLogger。 + +可采用Log4j或Log4j2来实现SLF4J。当采用Log4j实现SLF4J,需要添加如下jar包:log4j-\*.jar、slf4j-api-\*.jar、slf4j-log4\*-\*.jar,(\*区分版本),和配置文件:log4j.properties。若采用Log4j2实现SLF4J,需要添加如下jar包:log4j-api-\*.jar、log4j-core-\*.jar、log4j-slf4j18-impl-\*.jar、slf4j-api-*-alpha1.jar(\*区分版本),和配置文件:log4j2.xml。 + +此方式支持日志管控。SLF4J可通过文件中的相关配置实现强大的日志管控功能,建议使用此方式进行日志管理。 + +> 注意:此方式依赖slf4j的通用API接口,如org.slf4j.LoggerFactory.getLogger(String name)、org.slf4j.Logger.debug(String var1)、org.slf4j.Logger.info(String var1)、org.slf4j.Logger.warn(String warn)、org.slf4j.Logger.warn(String warn)等,若以上接口发生变更,日志将无法打印。 + +示例: + +``` +public static Connection GetConnection(String username, String passwd){ + + String sourceURL = "jdbc:opengauss://10.10.0.13:8000/postgres?logger=Slf4JLogger"; + Connection conn = null; + + try{ + //创建连接 + conn = DriverManager.getConnection(sourceURL,username,passwd); + System.out.println("Connection succeed!"); + }catch (Exception e){ + e.printStackTrace(); + return null; + } + return conn; +} +``` + +log4j.properties示例: + +``` +log4j.logger.org.opengauss=ALL, log_gsjdbc + +# 默认文件输出配置 +log4j.appender.log_gsjdbc=org.apache.log4j.RollingFileAppender +log4j.appender.log_gsjdbc.Append=true +log4j.appender.log_gsjdbc.File=gsjdbc.log +log4j.appender.log_gsjdbc.Threshold=TRACE +log4j.appender.log_gsjdbc.MaxFileSize=10MB +log4j.appender.log_gsjdbc.MaxBackupIndex=5 +log4j.appender.log_gsjdbc.layout=org.apache.log4j.PatternLayout +log4j.appender.log_gsjdbc.layout.ConversionPattern=%d %p %t %c - %m%n +log4j.appender.log_gsjdbc.File.Encoding = UTF-8 +``` + +log4j2.xml示例: + +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +方式二:对接应用程序使用的JdkLogger日志框架。 + +默认的Java日志记录框架将其配置存储在名为logging.properties的文件中。Java会在Java安装目录的文件夹中安装全局配置文件。logging.properties文件也可以创建并与单个项目一起存储。 + +logging.properties配置示例: + +``` +# 指定处理程序为文件。 +handlers= java.util.logging.FileHandler + +# 指定默认全局日志级别 +.level= ALL + +# 指定日志输出管控标准 +java.util.logging.FileHandler.level=ALL +java.util.logging.FileHandler.pattern = gsjdbc.log +java.util.logging.FileHandler.limit = 500000 +java.util.logging.FileHandler.count = 30 +java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter +java.util.logging.FileHandler.append=false +``` + +代码中使用示例: + +``` +System.setProperty("java.util.logging.FileHandler.pattern","jdbc.log"); +FileHandler fileHandler = new FileHandler(System.getProperty("java.util.logging.FileHandler.pattern")); +Formatter formatter = new SimpleFormatter(); +fileHandler.setFormatter(formatter); +Logger logger = Logger.getLogger("org.opengauss"); +logger.addHandler(fileHandler); +logger.setLevel(Level.ALL); +logger.setUseParentHandlers(false); +``` + +## 链路跟踪功能 + +MogDB JDBC驱动程序提供了应用到数据库的链路跟踪功能,用于将数据库端离散的SQL和应用程序的请求关联起来。该功能需要应用开发者实现org.opengauss.log.Tracer接口类,并在url中指定接口实现类的全限定名。 + +url示例: + +``` +String URL = "jdbc:opengauss://127.0.0.1:8000/postgres?traceInterfaceClass=xxx.xxx.xxx.OpenGaussTraceImpl"; +``` + +org.opengauss.log.Tracer接口类定义如下: + +``` +public interface Tracer { +// Retrieves the value of traceId. +String getTraceId(); +} +``` + +org.opengauss.log.Tracer接口实现类示例: + +``` +import org.opengauss.log.Tracer; + +public class OpenGaussTraceImpl implements Tracer { + private static MDC mdc = new MDC(); + + private final String TRACE_ID_KEY = "traceId"; + + public void set(String traceId) { + mdc.put(TRACE_ID_KEY, traceId); + } + + public void reset() { + mdc.clear(); + } + + @Override + public String getTraceId() { + return mdc.get(TRACE_ID_KEY); + } +} +``` + +上下文映射示例,用于存放不同请求的生成的traceId。 + +``` +import java.util.HashMap; + +public class MDC { + static final private ThreadLocal> threadLocal = new ThreadLocal<>(); + + public void put(String key, String val) { + if (key == null || val == null) { + throw new IllegalArgumentException("key or val cannot be null"); + } else { + if (threadLocal.get() == null) { + threadLocal.set(new HashMap<>()); + } + threadLocal.get().put(key, val); + } + } + + public String get(String key) { + if (key == null) { + throw new IllegalArgumentException("key cannot be null"); + } else if (threadLocal.get() == null) { + return null; + } else { + return threadLocal.get().get(key); + } + } + + public void clear() { + if (threadLocal.get() == null) { + return; + } else { + threadLocal.get().clear(); + } + } +} +``` + +业务使用traceId示例。 + +``` +String traceId = UUID.randomUUID().toString().replaceAll("-", ""); +openGaussTrace.set(traceId); +pstm = con.prepareStatement("select * from test_trace_id where id = ?"); +pstm.setInt(1, 1); +pstm.execute(); +pstm = con.prepareStatement("insert into test_trace_id values(?,?)"); +pstm.setInt(1, 2); +pstm.setString(2, "test"); +pstm.execute(); +openGaussTrace.reset(); +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/9-closing-a-connection.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/9-closing-a-connection.md new file mode 100644 index 00000000..6fac6024 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/2-development-based-on-jdbc/9-closing-a-connection.md @@ -0,0 +1,17 @@ +--- +title: 关闭连接 +summary: 关闭连接 +author: Guo Huan +date: 2021-06-07 +--- + +# 关闭连接 + +在使用数据库连接完成相应的数据操作后,需要关闭数据库连接。 + +关闭数据库连接可以直接调用其close方法。例如: + +``` +Connection conn = DriverManager.getConnection\("url","user","password"\) ; +conn.close\(\); +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/1-development-based-on-odbc-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/1-development-based-on-odbc-overview.md new file mode 100644 index 00000000..84f14591 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/1-development-based-on-odbc-overview.md @@ -0,0 +1,34 @@ +--- +title: 概述 +summary: 概述 +author: Guo Huan +date: 2021-04-26 +--- + +# 概述 + +ODBC(Open Database Connectivity,开放数据库互连)是由Microsoft公司基于X/OPEN CLI提出的用于访问数据库的应用程序编程接口。应用程序通过ODBC提供的API与数据库进行交互,增强了应用程序的可移植性、扩展性和可维护性。 + +ODBC的系统结构参见[图1](#ODBC)。 + +**图 1**ODBC系统机构 + +![ODBC系统机构](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/development-based-on-odbc-overview-1.png) + +MogDB目前在以下环境中提供对ODBC3.5的支持。 + +**表 1** ODBC支持平台 + +| 操作系统 | 平台 | +| :------------------------------------------------- | :------- | +| CentOS 6.4/6.5/6.6/6.7/6.8/6.9/7.0/7.1/7.2/7.3/7.4 | x86_64位 | +| CentOS 7.6 | ARM64位 | +| EulerOS 2.0 SP2/SP3 | x86_64位 | +| EulerOS 2.0 SP8 | ARM64位 | + +UNIX/Linux系统下的驱动程序管理器主要有unixODBC和iODBC,在这选择驱动管理器unixODBC-2.3.0作为连接数据库的组件。 + +Windows系统自带ODBC驱动程序管理器,在控制面板->管理工具中可以找到数据源(ODBC)选项。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** +> 当前数据库ODBC驱动基于开源版本,对于tinyint、smalldatetime、nvarchar2类型,在获取数据类型的时候,可能会出现不兼容。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/2-odbc-packages-dependent-libraries-and-header-files.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/2-odbc-packages-dependent-libraries-and-header-files.md new file mode 100644 index 00000000..809fc584 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/2-odbc-packages-dependent-libraries-and-header-files.md @@ -0,0 +1,14 @@ +--- +title: ODBC包及依赖的库和头文件 +summary: ODBC包及依赖的库和头文件 +author: Guo Huan +date: 2021-04-26 +--- + +# ODBC包及依赖的库和头文件 + +
+ +## Linux下的ODBC包 + +从发布包中获取,包名为[openGauss-x.x.x-ODBC.tar.gz](https://opengauss.org/zh/download.html)。Linux环境下,开发应用程序要用到unixODBC提供的头文件(sql.h、sqlext.h等)和库libodbc.so。这些头文件和库可从unixODBC-2.3.0的安装包中获得。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/3-configuring-a-data-source-in-the-linux-os.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/3-configuring-a-data-source-in-the-linux-os.md new file mode 100644 index 00000000..bd1619a5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/3-configuring-a-data-source-in-the-linux-os.md @@ -0,0 +1,334 @@ +--- +title: Linux下配置数据源 +summary: Linux下配置数据源 +author: Guo Huan +date: 2021-06-16 +--- + +# Linux下配置数据源 + +将MogDB提供的ODBC DRIVER(psqlodbcw.so)配置到数据源中便可使用。配置数据源需要配置"odbc.ini"和"odbcinst.ini"两个文件(在编译安装unixODBC过程中生成且默认放在"/usr/local/etc"目录下),并在服务器端进行配置。 + +
+ +## 操作步骤 + +1. 获取unixODBC源码包。 + + 获取参考地址: + + 下载后请先按照社区提供的完整性校验算法进行完整性校验。 + +2. 安装unixODBC。如果机器上已经安装了其他版本的unixODBC,可以直接覆盖安装。 + + 目前不支持unixODBC-2.2.1版本。以unixODBC-2.3.0版本为例,在客户端执行如下命令安装unixODBC。默认安装到"/usr/local"目录下,生成数据源文件到 "/usr/local/etc"目录下,库文件生成在"/usr/local/lib"目录。 + + ```bash + tar zxvf unixODBC-2.3.0.tar.gz + cd unixODBC-2.3.0 + #修改configure文件(如果不存在,那么请修改configure.ac),找到LIB_VERSION + #将它的值修改为"1:0:0",这样将编译出*.so.1的动态库,与psqlodbcw.so的依赖关系相同。 + vim configure + + ./configure --enable-gui=no #如果要在鲲鹏服务器上编译,请追加一个configure参数: --build=aarch64-unknown-linux-gnu + make + #安装可能需要root权限 + make install + ``` + +3. 替换客户端openGauss驱动程序。 + + a. 将openGauss-1.1.0-ODBC.tar.gz解压。解压后会得到两个文件夹:lib与odbc,在odbc文件夹中还会有一个lib文件夹。/odbc/lib中会有“psqlodbca.la”,“psqlodbca.so”,“psqlodbcw.la”和“psqlodbcw.so”四个文件,将这四个文件拷贝到“/usr/local/lib”目录下。 + + b. 将openGauss-1.1.0-ODBC.tar.gz解压后lib目录中的库拷贝到“/usr/local/lib”目录下。 + +4. 配置数据源。 + + a. 配置ODBC驱动文件。 + + 在`/usr/local/etc/odbcinst.ini`文件中追加以下内容。 + + ```bash + [GaussMPP] + Driver64=/usr/local/lib/psqlodbcw.so + setup=/usr/local/lib/psqlodbcw.so + ``` + + odbcinst.ini文件中的配置参数说明如[表1](#odbcinst.ini)所示。 + + **表 1** odbcinst.ini文件配置参数 + + | **参数** | **描述** | **示例** | + | :----------- | :------------------------------------------- | :----------------------------------- | + | [DriverName] | 驱动器名称,对应数据源DSN中的驱动名。 | [DRIVER_N] | + | Driver64 | 驱动动态库的路径。 | Driver64=/usr/local/lib/psqlodbcw.so | + | setup | 驱动安装路径,与Driver64中动态库的路径一致。 | setup=/usr/local/lib/psqlodbcw.so | + + b. 配置数据源文件。 + + 在`/usr/local/etc/odbc.ini`文件中追加以下内容。 + + ```bash + [MPPODBC] + Driver=GaussMPP + Servername=10.10.0.13(数据库Server IP) + Database=postgres (数据库名) + Username=omm (数据库用户名) + Password= (数据库用户密码) + Port=8000 (数据库侦听端口) + Sslmode=allow + ``` + + odbc.ini文件配置参数说明如[表2](#odbc.ini)所示。 + + **表 2** odbc.ini文件配置参数 + + | **参数** | **描述** | **示例** | + | :------------------- | :------------------ |--------------------| + | [DSN] | 数据源的名称。 | [MPPODBC]| + | Driver | 驱动名,对应odbcinst.ini中的DriverName。 | Driver=DRIVER_N| + | Servername | 服务器的IP地址。可配置多个IP地址。 | Servername=10.145.130.26| + | Database | 要连接的数据库的名称。 | Database=postgres | + | Username | 数据库用户名称。 | Username=omm | + | Password | 数据库用户密码。 | Password=
说明:
ODBC驱动本身已经对内存密码进行过清理,以保证用户密码在连接后不会再在内存中保留。
但是如果配置了此参数,由于UnixODBC对数据源文件等进行缓存,可能导致密码长期保留在内存中。
推荐在应用程序连接时,将密码传递给相应API,而非写在数据源配置文件中。同时连接成功后,应当及时清理保存密码的内存段。 | + | Port | 服务器的端口号。 | Port=8000 | + | Sslmode | 开启SSL模式 | Sslmode=allow | + | Debug | 设置为1时,将会打印psqlodbc驱动的mylog,日志生成目录为/tmp/。设置为0时则不会生成。 | Debug=1 | + | UseServerSidePrepare | 是否开启数据库端扩展查询协议。
可选值0或1,默认为1,表示打开扩展查询协议。 | UseServerSidePrepare=1 | + | UseBatchProtocol | 是否开启批量查询协议(打开可提高DML性能);可选值0或者1,默认为1。
当此值为0时,不使用批量查询协议(主要用于与早期数据库版本通信兼容)。
当此值为1,并且数据库support_batch_bind参数存在且为on时,将打开批量查询协议。 | UseBatchProtocol=1 | + | ForExtensionConnector | 这个开关控制着savepoint是否发送,savepoint相关问题可以注意这个开关。 | ForExtensionConnector=1 | + | UnamedPrepStmtThreshold | 每次调用SQLFreeHandle释放Stmt时,ODBC都会向server端发送一个Deallocate plan_name语句,业务中存在大量这类语句。为了减少这类语句的发送,我们将 stmt->plan_name置空,从而使得数据库识别这个为unamed stmt。增加这个参数对unamed stmt的阈值进行控制。 | UnamedPrepStmtThreshold=100 | + | ConnectionExtraInfo | GUC参数connection_info(参见[connection_info](../../../reference-guide/guc-parameters/3-connection-and-authentication/1-connection-settings.md#connection_info))中显示驱动部署路径和进程属主用户的开关。 | ConnectionExtraInfo=1
说明:
默认值为0。当设置为1时,ODBC驱动会将当前驱动的部署路径、进程属主用户上报到数据库中,记录在connection_info参数(参见[connection_info](../../../reference-guide/guc-parameters/3-connection-and-authentication/1-connection-settings.md#connection_info))里;同时可以在[PG_STAT_ACTIVITY](../../../reference-guide/system-catalogs-and-system-views/system-views/PG_STAT_ACTIVITY.md)中查询到。 | + | BoolAsChar | 设置为Yes是,Bools值将会映射为SQL_CHAR。如不设置将会映射为SQL_BIT。 | BoolsAsChar = Yes | + | RowVersioning | 当尝试更新一行数据时,设置为Yes会允许应用检测数据有没有被其他用户进行修改。 | RowVersioning=Yes | + | ShowSystemTables | 驱动将会默认系统表格为普通SQL表格。 | ShowSystemTables=Yes | + + 其中关于Sslmode的选项的允许值,具体信息见下表: + + **表 3** Sslmode的可选项及其描述 + + | sslmode | 是否会启用SSL加密 | 描述 | + | :---------- | :---------------- | :------------------------------ | + | disable | 否 | 不使用SSL安全连接。| + | allow | 可能 | 如果数据库服务器要求使用,则可以使用SSL安全加密连接,但不验证数据库服务器的真实性。| + | prefer | 可能 | 如果数据库支持,那么建议使用SSL安全加密连接,但不验证数据库服务器的真实性。 | + | require| 是 | 必须使用SSL安全连接,但是只做了数据加密,而并不验证数据库服务器的真实性。| + | verify-ca | 是 | 必须使用SSL安全连接,并且验证数据库是否具有可信证书机构签发的证书。 | + | verify-full | 是 | 必须使用SSL安全连接,在verify-ca的验证范围之外,同时验证数据库所在主机的主机名是否与证书内容一致。MogDB不支持此模式。 | + +5. (可选)生成SSL证书,具体请参见[证书生成](../../../security-guide/security/1-client-access-authentication.md#证书生成)。此步骤和[6](#6)在服务端与客户端通过ssl方式连接的情况下需要执行。非ssl方式连接情况下可以跳过。 + +6. (可选)替换SSL证书,具体请参见[证书替换](../../../security-guide/security/1-client-access-authentication.md#证书替换)。 + +7. SSL模式: + + 声明如下环境变量,同时保证client.key*系列文件为600权限: + + ``` + 退回根目录,创建.postgresql目录,并将root.crt,client.crt,client.key,client.key.cipher,client.key.rand,client.req,server.crt,server.key,server.key.cipher,server.key.rand,server.req放在此路径下。 + Unix系统下,server.crt、server.key的权限设置必须禁止任何外部或组的访问,请执行如下命令实现这一点。 + chmod 0600 server.key + 将root.crt以及server开头的证书相关文件全部拷贝进数据库install/data目录下(与postgresql.conf文件在同一路径)。 + 修改postgresql.conf文件: + ssl = on + ssl_cert_file = 'server.crt' + ssl_key_file = 'server.key' + ssl_ca_file = 'root.crt' + 修改完参数后需重启数据库。 + 修改配置文件odbc.ini中的sslmode参数(require或verify-ca)。 + ``` + +8. 配置数据库服务器。 + + a. 以操作系统用户omm登录数据库主节点。 + + b. 执行如下命令增加对外提供服务的网卡IP或者主机名(英文逗号分隔),其中NodeName为当前节点名称: + + ```bash + gs_guc reload -N NodeName -I all -c "listen_addresses='localhost,192.168.0.100,10.11.12.13'" + ``` + + 在DR(Direct Routing,LVS的直接路由DR模式)模式中需要将虚拟IP地址(10.11.12.13)加入到服务器的侦听地址列表中。 + + listen_addresses也可以配置为"\*"或"0.0.0.0",此配置下将侦听所有网卡,但存在安全风险,不推荐用户使用,推荐用户按照需要配置IP或者主机名,打开侦听。 + + c. 执行如下命令在数据库主节点配置文件中增加一条认证规则。(这里假设客户端IP地址为10.11.12.13,即远程连接的机器的IP地址) + + ```bash + gs_guc reload -N all -I all -h "host all jack 10.11.12.13/32 sha256" + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > + > - -N all表示MogDB中的所有主机。 + > - -I all表示主机中的所有实例。 + > - -h表示指定需要在"pg_hba.conf"增加的语句。 + > - all表示允许客户端连接到任意的数据库。 + > - jack表示连接数据库的用户。 + > - 10.11.12.13/32表示只允许IP地址为10.11.12.13的主机连接。在使用过程中,请根据用户的网络进行配置修改。32表示子网掩码为1的位数,即255.255.255.255 + > - sha256表示连接时jack用户的密码使用sha256算法加密。 + + 如果将ODBC客户端配置在和要连接的数据库主节点在同一台机器上,则可使用local trust认证方式,如下: + + ```bash + local all all trust + ``` + + 如果将ODBC客户端配置在和要连接的数据库主节点在不同机器上,则需要使用sha256认证方式,如下: + + ```bash + host all all xxx.xxx.xxx.xxx/32 sha256 + ``` + + d. 重启MogDB。 + + ```bash + gs_om -t stop + gs_om -t start + ``` + +9. 在客户端配置环境变量。 + + ``` + vim ~/.bashrc + ``` + + 在配置文件中追加以下内容。 + + ``` + export LD_LIBRARY_PATH=/usr/local/lib/:$LD_LIBRARY_PATH + export ODBCSYSINI=/usr/local/etc + export ODBCINI=/usr/local/etc/odbc.ini + ``` + +10. 执行如下命令使设置生效。 + + ``` + source ~/.bashrc + ``` + +
+ +## 测试数据源配置 + +执行./isql -v MPPODBC(数据源名称)命令。 + +- 如果显示如下信息,表明配置正确,连接成功。 + + ```bash + +---------------------------------------+ + | Connected! | + | | + | sql-statement | + | help [tablename] | + | quit | + | | + +---------------------------------------+ + SQL> + ``` + +- 若显示ERROR信息,则表明配置错误。请检查上述配置是否正确。 + +
+ +## 常见问题处理 + +- [UnixODBC]Can't open lib 'xxx/xxx/psqlodbcw.so' : file not found. + + 此问题的可能原因: + + - odbcinst.ini文件中配置的路径不正确 + + 确认的方法: 'ls'一下错误信息中的路径,以确保该psqlodbcw.so文件存在,同时具有执行权限。 + + - psqlodbcw.so的依赖库不存在,或者不在系统环境变量中 + + 确认的办法: ldd一下错误信息中的路径,如果是缺少libodbc.so.1等UnixODBC的库,那么按照"操作步骤"中的方法重新配置UnixODBC,并确保它的安装路径下的lib目录添加到了LD_LIBRARY_PATH中;如果是缺少其他库,请将ODBC驱动包中的lib目录添加到LD_LIBRARY_PATH中。 + +- [UnixODBC]connect to server failed: no such file or directory + + 此问题可能的原因: + + - 配置了错误的/不可达的数据库地址,或者端口 + + 请检查数据源配置中的Servername及Port配置项。 + + - 服务器侦听不正确 + + 如果确认Servername及Port配置正确,请根据"操作步骤"中数据库服务器的相关配置,确保数据库侦听了合适的网卡及端口。 + + - 防火墙及网闸设备 + + 请确认防火墙设置,将数据库的通信端口添加到可信端口中。 + + 如果有网闸设备,请确认一下相关的设置。 + +- [unixODBC]The password-stored method is not supported. + + 此问题可能原因: + + 数据源中未配置sslmode配置项。 + + 解决办法: + + 请配置该选项至allow或以上选项。此配置的更多信息,见[表3](#sslmode)。 + +- Server common name "xxxx" does not match host name "xxxxx" + + 此问题的原因: + + 使用了SSL加密的"verify-full"选项,驱动程序会验证证书中的主机名与实际部署数据库的主机名是否一致。 + + 解决办法: + + 碰到此问题可以使用"verify-ca"选项,不再校验主机名;或者重新生成一套与数据库所在主机名相同的CA证书。 + +- Driver's SQLAllocHandle on SQL_HANDLE_DBC failed + + 此问题的可能原因: + + 可执行文件(比如UnixODBC的isql,以下都以isql为例)与数据库驱动(psqlodbcw.so)依赖于不同的odbc的库版本: libodbc.so.1或者libodbc.so.2。此问题可以通过如下方式确认: + + ```bash + ldd `which isql` | grep odbc + ldd psqlodbcw.so | grep odbc + ``` + + 这时,如果输出的libodbc.so最后的后缀数字不同或者指向不同的磁盘物理文件,那么基本就可以断定是此问题。isql与psqlodbcw.so都会要求加载libodbc.so,这时如果它们加载的是不同的物理文件,便会导致两套完全同名的函数列表,同时出现在同一个可见域里(UnixODBC的libodbc.so.\*的函数导出列表完全一致),产生冲突,无法加载数据库驱动。 + + 解决办法: + + 确定一个要使用的UnixODBC,然后卸载另外一个(比如卸载库版本号为.so.2的UnixODBC),然后将剩下的.so.1的库,新建一个同名但是后缀为.so.2的软链接,便可解决此问题。 + +- FATAL: Forbid remote connection with trust method! + + 由于安全原因,数据库主节点禁止MogDB内部其他节点无认证接入。 + + 如果要在MogDB内部访问数据库主节点,请将ODBC程序部署在数据库主节点所在机器,服务器地址使用"127.0.0.1"。建议业务系统单独部署在MogDB外部,否则可能会影响数据库运行性能。 + +- [unixODBC]Invalid attribute value + + 有可能是unixODBC的版本并非推荐版本,建议通过"odbcinst -version"命令排查环境中的unixODBC版本。 + +- authentication method 10 not supported. + + 使用开源客户端碰到此问题,可能原因: + + 数据库中存储的口令校验只存储了SHA256格式哈希,而开源客户端只识别MD5校验,双方校验方法不匹配报错。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** + > + > - 数据库并不存储用户口令,只存储用户口令的哈希码。 + > - 数据库当用户更新用户口令或者新建用户时,会同时存储两种格式的哈希码,这时将兼容开源的认证协议。 + > - 但是当老版本升级到新版本时,由于哈希的不可逆性,所以数据库无法还原用户口令,进而生成新格式的哈希,所以仍然只保留了SHA256格式的哈希,导致仍然无法使用MD5做口令认证。 + > - MD5加密算法安全性低,存在安全风险,建议使用更安全的加密算法。 + + 要解决该问题,可以更新用户口令(参见[ALTER USER](../../../reference-guide/sql-syntax/ALTER-USER.md));或者新建一个用户(参见[CREATE USER](../../../reference-guide/sql-syntax/CREATE-USER.md)),赋于同等权限,使用新用户连接数据库。 + +- unsupported frontend protocol 3.51: server supports 1.0 to 3.0 + + 目标数据库版本过低,或者目标数据库为开源数据库。请使用对应版本的数据库驱动连接目标数据库。 + +- FATAL: GSS authentication method is not allowed because XXXX user password is not disabled. + + 目标数据库主节点的pg_hba.conf里配置了当前客户端IP使用"gss"方式来做认证,该认证算法不支持用作客户端的身份认证,请修改到"sha256"后再试。配置方法见[8](#8)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/4-development-process.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/4-development-process.md new file mode 100644 index 00000000..8497be1a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/4-development-process.md @@ -0,0 +1,44 @@ +--- +title: 开发流程 +summary: 开发流程 +author: Guo Huan +date: 2021-04-26 +--- + +# 开发流程 + +**图 1** ODBC开发应用程序的流程 + +![ODBC开发应用程序的流程](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/development-process-3.png) + +
+ +## 开发流程中涉及的API + +**表 1** 相关API说明 + +| **功能** | **API** | +| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | +| 申请句柄资源 | SQLAllocHandle: 申请句柄资源,可替代如下函数:
- SQLAllocEnv: 申请环境句柄
- SQLAllocConnect: 申请连接句柄
- SQLAllocStmt: 申请语句句柄 | +| 设置环境属性 | SQLSetEnvAttr | +| 设置连接属性 | SQLSetConnectAttr | +| 设置语句属性 | SQLSetStmtAttr | +| 连接数据源 | SQLConnect | +| 绑定缓冲区到结果集的列中 | SQLBindCol | +| 绑定SQL语句的参数标志和缓冲区 | SQLBindParameter | +| 查看最近一次操作错误信息 | SQLGetDiagRec | +| 为执行SQL语句做准备 | SQLPrepare | +| 执行一条准备好的SQL语句 | SQLExecute | +| 直接执行SQL语句 | SQLExecDirect | +| 结果集中取行集 | SQLFetch | +| 返回结果集中某一列的数据 | SQLGetData | +| 获取结果集中列的描述信息 | SQLColAttribute | +| 断开与数据源的连接 | SQLDisconnect | +| 释放句柄资源 | SQLFreeHandle: 释放句柄资源,可替代如下函数:
- SQLFreeEnv: 释放环境句柄
- SQLFreeConnect: 释放连接句柄
- SQLFreeStmt: 释放语句句柄 | + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** +> 数据库中收到的一次执行请求(不在事务块中),如果含有多条语句,将会被打包成一个事务,同时如果其中有一个语句失败,那么整个请求都将会被回滚。 +> +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **警告**: +> +> ODBC为应用程序与数据库的中心层,负责把应用程序发出的SQL指令传到数据库当中,自身并不解析SQL语法。故在应用程序中写入带有保密信息的SQL语句时(如明文密码),保密信息会被暴露在驱动日志中。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/5-example-common-functions-and-batch-binding.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/5-example-common-functions-and-batch-binding.md new file mode 100644 index 00000000..baf00804 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/5-example-common-functions-and-batch-binding.md @@ -0,0 +1,440 @@ +--- +title: 常用功能和批量绑定 +summary: 常用功能和批量绑定 +author: Guo Huan +date: 2021-04-26 +--- + +# 示例:常用功能和批量绑定 + +## 常用功能示例代码 + +``` +// 此示例演示如何通过ODBC方式获取MogDB中的数据。 +// DBtest.c (compile with: libodbc.so) +#include +#include +#include +#ifdef WIN32 +#include +#endif +SQLHENV V_OD_Env; // Handle ODBC environment +SQLHSTMT V_OD_hstmt; // Handle statement +SQLHDBC V_OD_hdbc; // Handle connection +char typename[100]; +SQLINTEGER value = 100; +SQLINTEGER V_OD_erg,V_OD_buffer,V_OD_err,V_OD_id; +int main(int argc,char *argv[]) +{ + // 1. 申请环境句柄 + V_OD_erg = SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&V_OD_Env); + if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) + { + printf("Error AllocHandle\n"); + exit(0); + } + // 2. 设置环境属性(版本信息) + SQLSetEnvAttr(V_OD_Env, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0); + // 3. 申请连接句柄 + V_OD_erg = SQLAllocHandle(SQL_HANDLE_DBC, V_OD_Env, &V_OD_hdbc); + if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) + { + SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); + exit(0); + } + // 4. 设置连接属性 + SQLSetConnectAttr(V_OD_hdbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_ON, 0); + // 5. 连接数据源,这里的“userName”与“password”分别表示连接数据库的用户名和用户密码,请根据实际情况修改。 + // 如果odbc.ini文件中已经配置了用户名密码,那么这里可以留空("");但是不建议这么做,因为一旦odbc.ini权限管理不善,将导致数据库用户密码泄露。 + V_OD_erg = SQLConnect(V_OD_hdbc, (SQLCHAR*) "gaussdb", SQL_NTS, + (SQLCHAR*) "userName", SQL_NTS, (SQLCHAR*) "password", SQL_NTS); + if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) + { + printf("Error SQLConnect %d\n",V_OD_erg); + SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); + exit(0); + } + printf("Connected !\n"); + // 6. 设置语句属性 + SQLSetStmtAttr(V_OD_hstmt,SQL_ATTR_QUERY_TIMEOUT,(SQLPOINTER *)3,0); + // 7. 申请语句句柄 + SQLAllocHandle(SQL_HANDLE_STMT, V_OD_hdbc, &V_OD_hstmt); + // 8. 直接执行SQL语句。 + SQLExecDirect(V_OD_hstmt,"drop table IF EXISTS customer_t1",SQL_NTS); + SQLExecDirect(V_OD_hstmt,"CREATE TABLE customer_t1(c_customer_sk INTEGER, c_customer_name VARCHAR(32));",SQL_NTS); + SQLExecDirect(V_OD_hstmt,"insert into customer_t1 values(25,li)",SQL_NTS); + // 9. 准备执行 + SQLPrepare(V_OD_hstmt,"insert into customer_t1 values(?)",SQL_NTS); + // 10. 绑定参数 + SQLBindParameter(V_OD_hstmt,1,SQL_PARAM_INPUT,SQL_C_SLONG,SQL_INTEGER,0,0, + &value,0,NULL); + // 11. 执行准备好的语句 + SQLExecute(V_OD_hstmt); + SQLExecDirect(V_OD_hstmt,"select id from testtable",SQL_NTS); + // 12. 获取结果集某一列的属性 + SQLColAttribute(V_OD_hstmt,1,SQL_DESC_TYPE,typename,100,NULL,NULL); + printf("SQLColAtrribute %s\n",typename); + // 13. 绑定结果集 + SQLBindCol(V_OD_hstmt,1,SQL_C_SLONG, (SQLPOINTER)&V_OD_buffer,150, + (SQLLEN *)&V_OD_err); + // 14. 通过SQLFetch取结果集中数据 + V_OD_erg=SQLFetch(V_OD_hstmt); + // 15. 通过SQLGetData获取并返回数据。 + while(V_OD_erg != SQL_NO_DATA) + { + SQLGetData(V_OD_hstmt,1,SQL_C_SLONG,(SQLPOINTER)&V_OD_id,0,NULL); + printf("SQLGetData ----ID = %d\n",V_OD_id); + V_OD_erg=SQLFetch(V_OD_hstmt); + }; + printf("Done !\n"); + // 16. 断开数据源连接并释放句柄资源 + SQLFreeHandle(SQL_HANDLE_STMT,V_OD_hstmt); + SQLDisconnect(V_OD_hdbc); + SQLFreeHandle(SQL_HANDLE_DBC,V_OD_hdbc); + SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); + return(0); + } +``` + +## 批量绑定示例代码 + +``` +/********************************************************************** +* 请在数据源中打开UseBatchProtocol,同时指定数据库中参数support_batch_bind +* 为on +* CHECK_ERROR的作用是检查并打印错误信息。 +* 此示例将与用户交互式获取DSN、模拟的数据量,忽略的数据量,并将最终数据入库到test_odbc_batch_insert中 +***********************************************************************/ +#include +#include +#include +#include +#include + +void Exec(SQLHDBC hdbc, SQLCHAR* sql) +{ + SQLRETURN retcode; // Return status + SQLHSTMT hstmt = SQL_NULL_HSTMT; // Statement handle + SQLCHAR loginfo[2048]; + + // Allocate Statement Handle + retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLAllocHandle(SQL_HANDLE_STMT) failed"); + return; + } + + // Prepare Statement + retcode = SQLPrepare(hstmt, (SQLCHAR*) sql, SQL_NTS); + sprintf((char*)loginfo, "SQLPrepare log: %s", (char*)sql); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLPrepare(hstmt, (SQLCHAR*) sql, SQL_NTS) failed"); + return; + } + + // Execute Statement + retcode = SQLExecute(hstmt); + sprintf((char*)loginfo, "SQLExecute stmt log: %s", (char*)sql); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLExecute(hstmt) failed"); + return; + } + // Free Handle + retcode = SQLFreeHandle(SQL_HANDLE_STMT, hstmt); + sprintf((char*)loginfo, "SQLFreeHandle stmt log: %s", (char*)sql); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLFreeHandle(SQL_HANDLE_STMT, hstmt) failed"); + return; + } +} + +int main () +{ + SQLHENV henv = SQL_NULL_HENV; + SQLHDBC hdbc = SQL_NULL_HDBC; + int batchCount = 1000; // 批量绑定的数据量 + SQLLEN rowsCount = 0; + int ignoreCount = 0; // 批量绑定的数据中,不要入库的数据量 + + SQLRETURN retcode; + SQLCHAR dsn[1024] = {'\0'}; + SQLCHAR loginfo[2048]; + + do + { + if (ignoreCount > batchCount) + { + printf("ignoreCount(%d) should be less than batchCount(%d)\n", ignoreCount, batchCount); + } + }while(ignoreCount > batchCount); + + retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLAllocHandle failed"); + goto exit; + } + + // Set ODBC Verion + retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, + (SQLPOINTER*)SQL_OV_ODBC3, 0); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLSetEnvAttr failed"); + goto exit; + } + + // Allocate Connection + retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLAllocHandle failed"); + goto exit; + } + + + // Set Login Timeout + retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLSetConnectAttr failed"); + goto exit; + } + + + // Set Auto Commit + retcode = SQLSetConnectAttr(hdbc, SQL_ATTR_AUTOCOMMIT, + (SQLPOINTER)(1), 0); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLSetConnectAttr failed"); + goto exit; + } + + + // Connect to DSN + // gaussdb替换成用户所使用的数据源名称 + sprintf(loginfo, "SQLConnect(DSN:%s)", dsn); + retcode = SQLConnect(hdbc, (SQLCHAR*) "gaussdb", SQL_NTS, + (SQLCHAR*) NULL, 0, NULL, 0); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLConnect failed"); + goto exit; + } + + // init table info. + Exec(hdbc, "drop table if exists test_odbc_batch_insert"); + Exec(hdbc, "create table test_odbc_batch_insert(id int primary key, col varchar2(50))"); + + // 下面的代码根据用户输入的数据量,构造出将要入库的数据: + { + SQLRETURN retcode; + SQLHSTMT hstmtinesrt = SQL_NULL_HSTMT; + int i; + SQLCHAR *sql = NULL; + SQLINTEGER *ids = NULL; + SQLCHAR *cols = NULL; + SQLLEN *bufLenIds = NULL; + SQLLEN *bufLenCols = NULL; + SQLUSMALLINT *operptr = NULL; + SQLUSMALLINT *statusptr = NULL; + SQLULEN process = 0; + + // 这里是按列构造,每个字段的内存连续存放在一起。 + ids = (SQLINTEGER*)malloc(sizeof(ids[0]) * batchCount); + cols = (SQLCHAR*)malloc(sizeof(cols[0]) * batchCount * 50); + // 这里是每个字段中,每一行数据的内存长度。 + bufLenIds = (SQLLEN*)malloc(sizeof(bufLenIds[0]) * batchCount); + bufLenCols = (SQLLEN*)malloc(sizeof(bufLenCols[0]) * batchCount); + // 该行是否需要被处理,SQL_PARAM_IGNORE 或 SQL_PARAM_PROCEED + operptr = (SQLUSMALLINT*)malloc(sizeof(operptr[0]) * batchCount); + memset(operptr, 0, sizeof(operptr[0]) * batchCount); + // 该行的处理结果。 + // 注:由于数据库中处理方式是同一语句隶属同一事务中,所以如果出错,那么待处理数据都将是出错的,并不会部分入库。 + statusptr = (SQLUSMALLINT*)malloc(sizeof(statusptr[0]) * batchCount); + memset(statusptr, 88, sizeof(statusptr[0]) * batchCount); + + if (NULL == ids || NULL == cols || NULL == bufLenCols || NULL == bufLenIds) + { + fprintf(stderr, "FAILED:\tmalloc data memory failed\n"); + goto exit; + } + + for (int i = 0; i < batchCount; i++) + { + ids[i] = i; + sprintf(cols + 50 * i, "column test value %d", i); + bufLenIds[i] = sizeof(ids[i]); + bufLenCols[i] = strlen(cols + 50 * i); + operptr[i] = (i < ignoreCount) ? SQL_PARAM_IGNORE : SQL_PARAM_PROCEED; + } + + // Allocate Statement Handle + retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtinesrt); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLAllocHandle failed"); + goto exit; + } + + // Prepare Statement + sql = (SQLCHAR*)"insert into test_odbc_batch_insert values(?, ?)"; + retcode = SQLPrepare(hstmtinesrt, (SQLCHAR*) sql, SQL_NTS); + sprintf((char*)loginfo, "SQLPrepare log: %s", (char*)sql); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLPrepare failed"); + goto exit; + } + + retcode = SQLSetStmtAttr(hstmtinesrt, SQL_ATTR_PARAMSET_SIZE, (SQLPOINTER)batchCount, sizeof(batchCount)); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLSetStmtAttr failed"); + goto exit; + } + + retcode = SQLBindParameter(hstmtinesrt, 1, SQL_PARAM_INPUT, SQL_C_SLONG, SQL_INTEGER, sizeof(ids[0]), 0,&(ids[0]), 0, bufLenIds); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLBindParameter failed"); + goto exit; + } + + retcode = SQLBindParameter(hstmtinesrt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 50, cols, 50, bufLenCols); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLBindParameter failed"); + goto exit; + } + + retcode = SQLSetStmtAttr(hstmtinesrt, SQL_ATTR_PARAMS_PROCESSED_PTR, (SQLPOINTER)&process, sizeof(process)); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLSetStmtAttr failed"); + goto exit; + } + + retcode = SQLSetStmtAttr(hstmtinesrt, SQL_ATTR_PARAM_STATUS_PTR, (SQLPOINTER)statusptr, sizeof(statusptr[0]) * batchCount); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLSetStmtAttr failed"); + goto exit; + } + + retcode = SQLSetStmtAttr(hstmtinesrt, SQL_ATTR_PARAM_OPERATION_PTR, (SQLPOINTER)operptr, sizeof(operptr[0]) * batchCount); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLSetStmtAttr failed"); + goto exit; + } + + retcode = SQLExecute(hstmtinesrt); + sprintf((char*)loginfo, "SQLExecute stmt log: %s", (char*)sql); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLExecute(hstmtinesrt) failed"); + goto exit; + + retcode = SQLRowCount(hstmtinesrt, &rowsCount); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLRowCount failed"); + goto exit; + } + + if (rowsCount != (batchCount - ignoreCount)) + { + sprintf(loginfo, "(batchCount - ignoreCount)(%d) != rowsCount(%d)", (batchCount - ignoreCount), rowsCount); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLExecute failed"); + goto exit; + } + } + else + { + sprintf(loginfo, "(batchCount - ignoreCount)(%d) == rowsCount(%d)", (batchCount - ignoreCount), rowsCount); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLExecute failed"); + goto exit; + } + } + + // check row number returned + if (rowsCount != process) + { + sprintf(loginfo, "process(%d) != rowsCount(%d)", process, rowsCount); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLExecute failed"); + goto exit; + } + } + else + { + sprintf(loginfo, "process(%d) == rowsCount(%d)", process, rowsCount); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLExecute failed"); + goto exit; + } + } + + for (int i = 0; i < batchCount; i++) + { + if (i < ignoreCount) + { + if (statusptr[i] != SQL_PARAM_UNUSED) + { + sprintf(loginfo, "statusptr[%d](%d) != SQL_PARAM_UNUSED", i, statusptr[i]); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLExecute failed"); + goto exit; + } + } + } + else if (statusptr[i] != SQL_PARAM_SUCCESS) + { + sprintf(loginfo, "statusptr[%d](%d) != SQL_PARAM_SUCCESS", i, statusptr[i]); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLExecute failed"); + goto exit; + } + } + } + + retcode = SQLFreeHandle(SQL_HANDLE_STMT, hstmtinesrt); + sprintf((char*)loginfo, "SQLFreeHandle hstmtinesrt"); + + if (!SQL_SUCCEEDED(retcode)) { + printf("SQLFreeHandle failed"); + goto exit; + } + } + + +exit: + (void) printf ("\nComplete.\n"); + + // Connection + if (hdbc != SQL_NULL_HDBC) { + SQLDisconnect(hdbc); + SQLFreeHandle(SQL_HANDLE_DBC, hdbc); + } + + // Environment + if (henv != SQL_NULL_HENV) + SQLFreeHandle(SQL_HANDLE_ENV, henv); + + return 0; +} +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/5.1-typical-application-scenarios-and-configurations.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/5.1-typical-application-scenarios-and-configurations.md new file mode 100644 index 00000000..de4a3c87 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/5.1-typical-application-scenarios-and-configurations.md @@ -0,0 +1,496 @@ +--- +title: 典型应用场景配置 +summary: 典型应用场景配置 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 典型应用场景配置 + +## 日志诊断场景 + +ODBC日志分为unixODBC驱动管理器日志和psqlODBC驱动端日志。前者可以用于追溯应用程序API的执行是否成功,后者是底层实现过程中的一些DFX日志,用来帮助定位问题。 + +unixODBC日志需要在odbcinst.ini文件中配置: + +```bash +[ODBC] +Trace=Yes +TraceFile=/path/to/odbctrace.log + +[GaussMPP] +Driver64=/usr/local/lib/psqlodbcw.so +setup=/usr/local/lib/psqlodbcw.so +``` + +psqlODBC日志只需要在odbc.ini加上: + +```bash +[gaussdb] +Driver=GaussMPP +Servername=10.10.0.13(数据库Server IP) +... +Debug=1(打开驱动端debug日志) +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: unixODBC日志将会生成在TraceFile配置的路径下,psqlODBC会在系统/tmp/下生成mylog_xxx.log。 + +## 高性能场景 + +进行大量数据插入时,建议如下: + +- 需要设置批量绑定:odbc.ini配置文件中设置UseBatchProtocol=1、数据库设置support_batch_bind=on。 +- ODBC程序绑定类型要和数据库中类型一致。 +- 客户端字符集和数据库字符集一致。 +- 事务改成手动提交。 + +odbc.ini配置文件: + +```bash +[gaussdb] +Driver=GaussMPP +Servername=10.10.0.13(数据库Server IP) +... +UseBatchProtocol=1 (默认打开) +ConnSettings=set client_encoding=UTF8 (设置客户端字符编码,保证和server端一致) +``` + +绑定类型用例: + +```c +#include +#include +#include +#include +#include +#include + +#define MESSAGE_BUFFER_LEN 128 +SQLHANDLE h_env = NULL; +SQLHANDLE h_conn = NULL; +SQLHANDLE h_stmt = NULL; +void print_error() +{ + SQLCHAR Sqlstate[SQL_SQLSTATE_SIZE+1]; + SQLINTEGER NativeError; + SQLCHAR MessageText[MESSAGE_BUFFER_LEN]; + SQLSMALLINT TextLength; + SQLRETURN ret = SQL_ERROR; + + ret = SQLGetDiagRec(SQL_HANDLE_STMT, h_stmt, 1, Sqlstate, &NativeError, MessageText, MESSAGE_BUFFER_LEN, &TextLength); + if ( SQL_SUCCESS == ret) + { + printf("\n STMT ERROR-%05d %s", NativeError, MessageText); + return; + } + + ret = SQLGetDiagRec(SQL_HANDLE_DBC, h_conn, 1, Sqlstate, &NativeError, MessageText, MESSAGE_BUFFER_LEN, &TextLength); + if ( SQL_SUCCESS == ret) + { + printf("\n CONN ERROR-%05d %s", NativeError, MessageText); + return; + } + + ret = SQLGetDiagRec(SQL_HANDLE_ENV, h_env, 1, Sqlstate, &NativeError, MessageText, MESSAGE_BUFFER_LEN, &TextLength); + if ( SQL_SUCCESS == ret) + { + printf("\n ENV ERROR-%05d %s", NativeError, MessageText); + return; + } + + return; +} + +/* 期盼函数返回SQL_SUCCESS */ +#define RETURN_IF_NOT_SUCCESS(func) \ +{\ + SQLRETURN ret_value = (func);\ + if (SQL_SUCCESS != ret_value)\ + {\ + print_error();\ + printf("\n failed line = %u: expect SQL_SUCCESS, but ret = %d", __LINE__, ret_value);\ + return SQL_ERROR; \ + }\ +} + +/* 期盼函数返回SQL_SUCCESS */ +#define RETURN_IF_NOT_SUCCESS_I(i, func) \ +{\ + SQLRETURN ret_value = (func);\ + if (SQL_SUCCESS != ret_value)\ + {\ + print_error();\ + printf("\n failed line = %u (i=%d): : expect SQL_SUCCESS, but ret = %d", __LINE__, (i), ret_value);\ + return SQL_ERROR; \ + }\ +} + +/* 期盼函数返回SQL_SUCCESS_WITH_INFO */ +#define RETURN_IF_NOT_SUCCESS_INFO(func) \ +{\ + SQLRETURN ret_value = (func);\ + if (SQL_SUCCESS_WITH_INFO != ret_value)\ + {\ + print_error();\ + printf("\n failed line = %u: expect SQL_SUCCESS_WITH_INFO, but ret = %d", __LINE__, ret_value);\ + return SQL_ERROR; \ + }\ +} + +/* 期盼数值相等 */ +#define RETURN_IF_NOT(expect, value) \ +if ((expect) != (value))\ +{\ + printf("\n failed line = %u: expect = %u, but value = %u", __LINE__, (expect), (value)); \ + return SQL_ERROR;\ +} + +/* 期盼字符串相同 */ +#define RETURN_IF_NOT_STRCMP_I(i, expect, value) \ +if (( NULL == (expect) ) || (NULL == (value)))\ +{\ + printf("\n failed line = %u (i=%u): input NULL pointer !", __LINE__, (i)); \ + return SQL_ERROR; \ +}\ +else if (0 != strcmp((expect), (value)))\ +{\ + printf("\n failed line = %u (i=%u): expect = %s, but value = %s", __LINE__, (i), (expect), (value)); \ + return SQL_ERROR;\ +} + + +// prepare + execute SQL语句 +int execute_cmd(SQLCHAR *sql) +{ + if ( NULL == sql ) + { + return SQL_ERROR; + } + + if ( SQL_SUCCESS != SQLPrepare(h_stmt, sql, SQL_NTS)) + { + return SQL_ERROR; + } + + if ( SQL_SUCCESS != SQLExecute(h_stmt)) + { + return SQL_ERROR; + } + + return SQL_SUCCESS; +} +// execute + commit 句柄 +int commit_exec() +{ + if ( SQL_SUCCESS != SQLExecute(h_stmt)) + { + return SQL_ERROR; + } + + // 手动提交 + if ( SQL_SUCCESS != SQLEndTran(SQL_HANDLE_DBC, h_conn, SQL_COMMIT)) + { + return SQL_ERROR; + } + + return SQL_SUCCESS; +} + +int begin_unit_test() +{ + SQLINTEGER ret; + + /* 申请环境句柄 */ + ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &h_env); + if ((SQL_SUCCESS != ret) && (SQL_SUCCESS_WITH_INFO != ret)) + { + printf("\n begin_unit_test::SQLAllocHandle SQL_HANDLE_ENV failed ! ret = %d", ret); + return SQL_ERROR; + } + + /* 进行连接前必须要先设置版本号 */ + if (SQL_SUCCESS != SQLSetEnvAttr(h_env, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0)) + { + print_error(); + printf("\n begin_unit_test::SQLSetEnvAttr SQL_ATTR_ODBC_VERSION failed ! ret = %d", ret); + SQLFreeHandle(SQL_HANDLE_ENV, h_env); + return SQL_ERROR; + } + + /* 申请连接句柄 */ + ret = SQLAllocHandle(SQL_HANDLE_DBC, h_env, &h_conn); + if (SQL_SUCCESS != ret) + { + print_error(); + printf("\n begin_unit_test::SQLAllocHandle SQL_HANDLE_DBC failed ! ret = %d", ret); + SQLFreeHandle(SQL_HANDLE_ENV, h_env); + return SQL_ERROR; + } + + /* 建立连接 */ + ret = SQLConnect(h_conn, (SQLCHAR*) "gaussdb", SQL_NTS, + (SQLCHAR*) NULL, 0, NULL, 0); + if (SQL_SUCCESS != ret) + { + print_error(); + printf("\n begin_unit_test::SQLConnect failed ! ret = %d", ret); + SQLFreeHandle(SQL_HANDLE_DBC, h_conn); + SQLFreeHandle(SQL_HANDLE_ENV, h_env); + return SQL_ERROR; + } + + /* 申请语句句柄 */ + ret = SQLAllocHandle(SQL_HANDLE_STMT, h_conn, &h_stmt); + if (SQL_SUCCESS != ret) + { + print_error(); + printf("\n begin_unit_test::SQLAllocHandle SQL_HANDLE_STMT failed ! ret = %d", ret); + SQLFreeHandle(SQL_HANDLE_DBC, h_conn); + SQLFreeHandle(SQL_HANDLE_ENV, h_env); + return SQL_ERROR; + } + + return SQL_SUCCESS; +} + +void end_unit_test() +{ + /* 释放语句句柄 */ + if (NULL != h_stmt) + { + SQLFreeHandle(SQL_HANDLE_STMT, h_stmt); + } + + /* 释放连接句柄 */ + if (NULL != h_conn) + { + SQLDisconnect(h_conn); + SQLFreeHandle(SQL_HANDLE_DBC, h_conn); + } + + /* 释放环境句柄 */ + if (NULL != h_env) + { + SQLFreeHandle(SQL_HANDLE_ENV, h_env); + } + + return; +} + +int main() +{ + // begin test + if (begin_unit_test() != SQL_SUCCESS) + { + printf("\n begin_test_unit failed."); + return SQL_ERROR; + } + // 句柄配置同前面用例 + int i = 0; + SQLCHAR* sql_drop = "drop table if exists test_bindnumber_001"; + SQLCHAR* sql_create = "create table test_bindnumber_001(" + "f4 number, f5 number(10, 2)" + ")"; + SQLCHAR* sql_insert = "insert into test_bindnumber_001 values(?, ?)"; + SQLCHAR* sql_select = "select * from test_bindnumber_001"; + SQLLEN RowCount; + SQL_NUMERIC_STRUCT st_number; + SQLCHAR getValue[2][MESSAGE_BUFFER_LEN]; + + /* step 1. 建表 */ + RETURN_IF_NOT_SUCCESS(execute_cmd(sql_drop)); + RETURN_IF_NOT_SUCCESS(execute_cmd(sql_create)); + + /* step 2.1 通过SQL_NUMERIC_STRUCT结构绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + + //第一行: 1234.5678 + memset(st_number.val, 0, SQL_MAX_NUMERIC_LEN); + st_number.precision = 8; + st_number.scale = 4; + st_number.sign = 1; + st_number.val[0] = 0x4E; + st_number.val[1] = 0x61; + st_number.val[2] = 0xBC; + + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_NUMERIC, SQL_NUMERIC, sizeof(SQL_NUMERIC_STRUCT), 4, &st_number, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_NUMERIC, SQL_NUMERIC, sizeof(SQL_NUMERIC_STRUCT), 4, &st_number, 0, NULL)); + + // 关闭自动提交 + SQLSetConnectAttr(h_conn, SQL_ATTR_AUTOCOMMIT, (SQLPOINTER)SQL_AUTOCOMMIT_OFF, 0); + + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + //第二行: 12345678 + memset(st_number.val, 0, SQL_MAX_NUMERIC_LEN); + st_number.precision = 8; + st_number.scale = 0; + st_number.sign = 1; + st_number.val[0] = 0x4E; + st_number.val[1] = 0x61; + st_number.val[2] = 0xBC; + + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_NUMERIC, SQL_NUMERIC, sizeof(SQL_NUMERIC_STRUCT), 0, &st_number, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_NUMERIC, SQL_NUMERIC, sizeof(SQL_NUMERIC_STRUCT), 0, &st_number, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + //第三行: 12345678 + memset(st_number.val, 0, SQL_MAX_NUMERIC_LEN); + st_number.precision = 0; + st_number.scale = 4; + st_number.sign = 1; + st_number.val[0] = 0x4E; + st_number.val[1] = 0x61; + st_number.val[2] = 0xBC; + + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_NUMERIC, SQL_NUMERIC, sizeof(SQL_NUMERIC_STRUCT), 4, &st_number, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_NUMERIC, SQL_NUMERIC, sizeof(SQL_NUMERIC_STRUCT), 4, &st_number, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + + /* step 2.2 第四行通过SQL_C_CHAR字符串绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + SQLCHAR* szNumber = "1234.5678"; + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_NUMERIC, strlen(szNumber), 0, szNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_NUMERIC, strlen(szNumber), 0, szNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + /* step 2.3 第五行通过SQL_C_FLOAT绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + SQLREAL fNumber = 1234.5678; + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_FLOAT, SQL_NUMERIC, sizeof(fNumber), 4, &fNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_FLOAT, SQL_NUMERIC, sizeof(fNumber), 4, &fNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + /* step 2.4 第六行通过SQL_C_DOUBLE绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + SQLDOUBLE dNumber = 1234.5678; + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_NUMERIC, sizeof(dNumber), 4, &dNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_NUMERIC, sizeof(dNumber), 4, &dNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + SQLBIGINT bNumber1 = 0xFFFFFFFFFFFFFFFF; + SQLBIGINT bNumber2 = 12345; + + /* step 2.5 第七行通过SQL_C_SBIGINT绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_SBIGINT, SQL_NUMERIC, sizeof(bNumber1), 4, &bNumber1, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_SBIGINT, SQL_NUMERIC, sizeof(bNumber2), 4, &bNumber2, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + /* step 2.6 第八行通过SQL_C_UBIGINT绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_UBIGINT, SQL_NUMERIC, sizeof(bNumber1), 4, &bNumber1, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_UBIGINT, SQL_NUMERIC, sizeof(bNumber2), 4, &bNumber2, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + SQLLEN lNumber1 = 0xFFFFFFFFFFFFFFFF; + SQLLEN lNumber2 = 12345; + + /* step 2.7 第九行通过SQL_C_LONG绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_NUMERIC, sizeof(lNumber1), 0, &lNumber1, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_LONG, SQL_NUMERIC, sizeof(lNumber2), 0, &lNumber2, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + /* step 2.8 第十行通过SQL_C_ULONG绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_ULONG, SQL_NUMERIC, sizeof(lNumber1), 0, &lNumber1, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_ULONG, SQL_NUMERIC, sizeof(lNumber2), 0, &lNumber2, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + SQLSMALLINT sNumber = 0xFFFF; + + /* step 2.9 第十一行通过SQL_C_SHORT绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_SHORT, SQL_NUMERIC, sizeof(sNumber), 0, &sNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_SHORT, SQL_NUMERIC, sizeof(sNumber), 0, &sNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + /* step 2.10 第十二行通过SQL_C_USHORT绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_USHORT, SQL_NUMERIC, sizeof(sNumber), 0, &sNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_USHORT, SQL_NUMERIC, sizeof(sNumber), 0, &sNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + SQLCHAR cNumber = 0xFF; + + /* step 2.11 第十三行通过SQL_C_TINYINT绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_TINYINT, SQL_NUMERIC, sizeof(cNumber), 0, &cNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_TINYINT, SQL_NUMERIC, sizeof(cNumber), 0, &cNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + /* step 2.12 第十四行通过SQL_C_UTINYINT绑定参数 */ + RETURN_IF_NOT_SUCCESS(SQLPrepare(h_stmt, sql_insert, SQL_NTS)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 1, SQL_PARAM_INPUT, SQL_C_UTINYINT, SQL_NUMERIC, sizeof(cNumber), 0, &cNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(SQLBindParameter(h_stmt, 2, SQL_PARAM_INPUT, SQL_C_UTINYINT, SQL_NUMERIC, sizeof(cNumber), 0, &cNumber, 0, NULL)); + RETURN_IF_NOT_SUCCESS(commit_exec()); + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(1, RowCount); + + /* 用字符串类型统一进行期盼 */ + SQLCHAR* expectValue[14][2] = {{"1234.5678", "1234.57"}, + {"12345678", "12345678"}, + {"0", "0"}, + {"1234.5678", "1234.57"}, + {"1234.5677", "1234.57"}, + {"1234.5678", "1234.57"}, + {"-1", "12345"}, + {"18446744073709551615", "12345"}, + {"-1", "12345"}, + {"4294967295", "12345"}, + {"-1", "-1"}, + {"65535", "65535"}, + {"-1", "-1"}, + {"255", "255"}, + }; + + RETURN_IF_NOT_SUCCESS(execute_cmd(sql_select)); + while ( SQL_NO_DATA != SQLFetch(h_stmt)) + { + RETURN_IF_NOT_SUCCESS_I(i, SQLGetData(h_stmt, 1, SQL_C_CHAR, &getValue[0], MESSAGE_BUFFER_LEN, NULL)); + RETURN_IF_NOT_SUCCESS_I(i, SQLGetData(h_stmt, 2, SQL_C_CHAR, &getValue[1], MESSAGE_BUFFER_LEN, NULL)); + + //RETURN_IF_NOT_STRCMP_I(i, expectValue[i][0], getValue[0]); + //RETURN_IF_NOT_STRCMP_I(i, expectValue[i][1], getValue[1]); + i++; + } + + RETURN_IF_NOT_SUCCESS(SQLRowCount(h_stmt, &RowCount)); + RETURN_IF_NOT(i, RowCount); + SQLCloseCursor(h_stmt); + /* step final. 删除表还原环境 */ + RETURN_IF_NOT_SUCCESS(execute_cmd(sql_drop)); + + end_unit_test(); +} +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: 上述用例中定义了number列,调用SQLBindParameter接口时,绑定SQL_NUMERIC会比SQL_LONG性能高一些。因为如果是char,在数据库服务端插入数据时需要进行数据类型转换,从而引发性能瓶颈。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-0-odbc-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-0-odbc-overview.md new file mode 100644 index 00000000..fece7822 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-0-odbc-overview.md @@ -0,0 +1,10 @@ +--- +title: 说明 +summary: 说明 +author: Guo Huan +date: 2021-05-17 +--- + +# 说明 + +ODBC接口是一套提供给用户的API函数,本节将对部分常用接口做具体描述,若涉及其他接口可参考[msdn](https://msdn.microsoft.com/en-us/library/windows/desktop/ms714177(v=vs.85).aspx)中“ODBC Programmer's Reference”项的相关内容。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-1-SQLAllocEnv.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-1-SQLAllocEnv.md new file mode 100644 index 00000000..e3340b02 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-1-SQLAllocEnv.md @@ -0,0 +1,10 @@ +--- +title: SQLAllocEnv +summary: SQLAllocEnv +author: Guo Huan +date: 2021-05-17 +--- + +# SQLAllocEnv + +在ODBC 3.x版本中,ODBC 2.x的函数SQLAllocEnv已被SQLAllocHandle代替。有关详细信息请参阅[SQLAllocHandle](2-3-SQLAllocHandle.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-10-SQLExecDirect.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-10-SQLExecDirect.md new file mode 100644 index 00000000..7d1a494d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-10-SQLExecDirect.md @@ -0,0 +1,48 @@ +--- +title: SQLExecDirect +summary: SQLExecDirect +author: Guo Huan +date: 2021-05-17 +--- + +# SQLExecDirect + +## 功能描述 + +使用参数的当前值,执行一条准备好的语句。对于一次只执行一条SQL语句,SQLExecDirect是最快的执行方式。 + +## 原型 + +``` +SQLRETURN SQLExecDirect(SQLHSTMT StatementHandle, + SQLCHAR *StatementText, + SQLINTEGER TextLength); +``` + +## 参数 + +**表 1** SQLExecDirect参数 + +| **关键字** | **参数说明** | +| :-------------- | :---------------------------------------- | +| StatementHandle | 语句句柄,通过SQLAllocHandle获得。 | +| StatementText | 要执行的SQL语句。不支持一次执行多条语句。 | +| TextLength | StatementText的长度。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_NEED_DATA:在执行SQL语句前没有提供足够的参数。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 +- SQL_STILL_EXECUTING:表示语句正在执行。 +- SQL_NO_DATA:表示SQL语句不返回结果集。 + +## 注意事项 + +当调用SQLExecDirect函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-11-SQLExecute.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-11-SQLExecute.md new file mode 100644 index 00000000..7a820ecd --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-11-SQLExecute.md @@ -0,0 +1,44 @@ +--- +title: SQLExecute +summary: SQLExecute +author: Guo Huan +date: 2021-05-17 +--- + +# SQLExecute + +## 功能描述 + +如果语句中存在参数标记的话,SQLExecute函数使用参数标记参数的当前值,执行一条准备好的SQL语句。 + +## 原型 + +``` +SQLRETURN SQLExecute(SQLHSTMT StatementHandle); +``` + +## 参数 + +**表 1** SQLExecute参数 + +| **关键字** | **参数说明** | +| :-------------- | :--------------------- | +| StatementHandle | 要执行语句的语句句柄。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_NEED_DATA:表示在执行SQL语句前没有提供足够的参数。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_NO_DATA:表示SQL语句不返回结果集。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 +- SQL_STILL_EXECUTING:表示语句正在执行。 + +## 注意事项 + +当SQLExecute函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,可通过调用SQLGetDiagRec函数,并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-12-SQLFetch.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-12-SQLFetch.md new file mode 100644 index 00000000..4e69a482 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-12-SQLFetch.md @@ -0,0 +1,43 @@ +--- +title: SQLFetch +summary: SQLFetch +author: Guo Huan +date: 2021-05-17 +--- + +# SQLFetch + +## 功能描述 + +从结果集中取下一个行集的数据,并返回所有被绑定列的数据。 + +## 原型 + +``` +SQLRETURN SQLFetch(SQLHSTMT StatementHandle); +``` + +## 参数 + +**表 1** SQLFetch参数 + +| **关键字** | **参数说明** | +| :-------------- | :--------------------------------- | +| StatementHandle | 语句句柄,通过SQLAllocHandle获得。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_NO_DATA:表示SQL语句不返回结果集。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 +- SQL_STILL_EXECUTING:表示语句正在执行。 + +## 注意事项 + +当调用SQLFetch函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-13-SQLFreeStmt.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-13-SQLFreeStmt.md new file mode 100644 index 00000000..e0e9bb86 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-13-SQLFreeStmt.md @@ -0,0 +1,10 @@ +--- +title: SQLFreeStmt +summary: SQLFreeStmt +author: Guo Huan +date: 2021-05-17 +--- + +# SQLFreeStmt + +在ODBC 3.x版本中,ODBC 2.x的函数SQLFreeStmt已被SQLFreeHandle代替。有关详细信息请参阅[SQLFreeHandle](2-15-SQLFreeHandle.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-14-SQLFreeConnect.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-14-SQLFreeConnect.md new file mode 100644 index 00000000..c9a2eb3c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-14-SQLFreeConnect.md @@ -0,0 +1,10 @@ +--- +title: SQLFreeConnect +summary: SQLFreeConnect +author: Guo Huan +date: 2021-05-17 +--- + +# SQLFreeConnect + +在ODBC 3.x版本中,ODBC 2.x的函数SQLFreeConnect已被SQLFreeHandle代替。有关详细信息请参阅[SQLFreeHandle](2-15-SQLFreeHandle.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-15-SQLFreeHandle.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-15-SQLFreeHandle.md new file mode 100644 index 00000000..fd467d8f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-15-SQLFreeHandle.md @@ -0,0 +1,43 @@ +--- +title: SQLFreeHandle +summary: SQLFreeHandle +author: Guo Huan +date: 2021-05-17 +--- + +# SQLFreeHandle + +## 功能描述 + +释放与指定环境、连接、语句或描述符相关联的资源,它替代了ODBC 2.x函数SQLFreeEnv、SQLFreeConnect及SQLFreeStmt。 + +## 原型 + +``` +SQLRETURN SQLFreeHandle(SQLSMALLINT HandleType, + SQLHANDLE Handle); +``` + +## 参数 + +**表 1** SQLFreeHandle参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------------------------------------------- | +| HandleType | SQLFreeHandle要释放的句柄类型。必须为下列值之一:
- SQL_HANDLE_ENV
- SQL_HANDLE_DBC
- SQL_HANDLE_STMT
- SQL_HANDLE_DESC
如果HandleType不是这些值之一,SQLFreeHandle返回SQL_INVALID_HANDLE。 | +| Handle | 要释放的句柄。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +如果SQLFreeHandle返回SQL_ERROR,句柄仍然有效。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-16-SQLFreeEnv.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-16-SQLFreeEnv.md new file mode 100644 index 00000000..fc067324 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-16-SQLFreeEnv.md @@ -0,0 +1,10 @@ +--- +title: SQLFreeEnv +summary: SQLFreeEnv +author: Guo Huan +date: 2021-05-17 +--- + +# SQLFreeEnv + +在ODBC 3.x版本中,ODBC 2.x的函数SQLFreeEnv已被SQLFreeHandle代替。有关详细信息请参阅[SQLFreeHandle](2-15-SQLFreeHandle.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-17-SQLPrepare.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-17-SQLPrepare.md new file mode 100644 index 00000000..1f844fdf --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-17-SQLPrepare.md @@ -0,0 +1,46 @@ +--- +title: SQLPrepare +summary: SQLPrepare +author: Guo Huan +date: 2021-05-17 +--- + +# SQLPrepare + +## 功能描述 + +准备一个将要进行的SQL语句。 + +## 原型 + +``` +SQLRETURN SQLPrepare(SQLHSTMT StatementHandle, + SQLCHAR *StatementText, + SQLINTEGER TextLength); +``` + +## 参数 + +**表 1** SQLPrepare参数 + +| **关键字** | **参数说明** | +| :-------------- | :-------------------- | +| StatementHandle | 语句句柄。 | +| StatementText | SQL文本串。 | +| TextLength | StatementText的长度。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 +- SQL_STILL_EXECUTING:表示语句正在执行。 + +## 注意事项 + +当SQLPrepare返回的值为SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数分别设置为SQL_HANDLE_STMT和StatementHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-18-SQLGetData.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-18-SQLGetData.md new file mode 100644 index 00000000..42ce2240 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-18-SQLGetData.md @@ -0,0 +1,53 @@ +--- +title: SQLGetData +summary: SQLGetData +author: Guo Huan +date: 2021-05-17 +--- + +# SQLGetData + +## 功能描述 + +SQLGetData返回结果集中某一列的数据。可以多次调用它来部分地检索不定长度的数据。 + +## 原型 + +``` +SQLRETURN SQLGetData(SQLHSTMT StatementHandle, + SQLUSMALLINT Col_or_Param_Num, + SQLSMALLINT TargetType, + SQLPOINTER TargetValuePtr, + SQLLEN BufferLength, + SQLLEN *StrLen_or_IndPtr); +``` + +## 参数 + +**表 1** SQLGetData参数 + +| **关键字** | **参数说明** | +| :--------------- | :----------------------------------------------------------- | +| StatementHandle | 语句句柄,通过SQLAllocHandle获得。 | +| Col_or_Param_Num | 要返回数据的列号。结果集的列按增序从1开始编号。书签列的列号为0。 | +| TargetType | TargetValuePtr缓冲中的C数据类型的类型标识符。若TargetType为SQL_ARD_TYPE,驱动使用ARD中SQL_DESC_CONCISE_TYPE字段的类型标识符。若为SQL_C_DEFAULT,驱动根据源的SQL数据类型选择缺省的数据类型。 | +| TargetValuePtr | **输出参数**:指向返回数据所在缓冲区的指针。 | +| BufferLength | TargetValuePtr所指向缓冲区的长度。 | +| StrLen_or_IndPtr | **输出参数**:指向缓冲区的指针,在此缓冲区中返回长度或标识符的值。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_NO_DATA:表示SQL语句不返回结果集。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 +- SQL_STILL_EXECUTING:表示语句正在执行。 + +## 注意事项 + +当调用SQLGetData函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数分别设置为SQL_HANDLE_STMT和StatementHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-19-SQLGetDiagRec.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-19-SQLGetDiagRec.md new file mode 100644 index 00000000..c4fb9129 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-19-SQLGetDiagRec.md @@ -0,0 +1,74 @@ +--- +title: SQLGetDiagRec +summary: SQLGetDiagRec +author: Guo Huan +date: 2021-05-17 +--- + +# SQLGetDiagRec + +## 功能描述 + +返回诊断记录的多个字段的当前值,其中诊断记录包含错误、警告及状态信息。 + +## 原型 + +``` +SQLRETURN SQLGetDiagRec(SQLSMALLINT HandleType + SQLHANDLE Handle, + SQLSMALLINT RecNumber, + SQLCHAR *SQLState, + SQLINTEGER *NativeErrorPtr, + SQLCHAR *MessageText, + SQLSMALLINT BufferLength + SQLSMALLINT *TextLengthPtr); +``` + +## 参数 + +**表 1** SQLGetDiagRec参数 + +| **关键字** | **参数说明** | +| :------------- | :----------------------------------------------------------- | +| HandleType | 句柄类型标识符,它说明诊断所要求的句柄类型。必须为下列值之一:
- SQL_HANDLE_ENV
- SQL_HANDLE_DBC
- SQL_HANDLE_STMT
- SQL_HANDLE_DESC | +| Handle | 诊断数据结构的句柄,其类型由HandleType来指出。如果HandleType是SQL_HANDLE_ENV,Handle可以是共享的或非共享的环境句柄。 | +| RecNumber | 指出应用从查找信息的状态记录。状态记录从1开始编号。 | +| SQLState | **输出参数**:指向缓冲区的指针,该缓冲区存储着有关RecNumber的五字符的SQLSTATE码。 | +| NativeErrorPtr | **输出参数**:指向缓冲区的指针,该缓冲区存储着本地的错误码。 | +| MessageText | 指向缓冲区的指针,该缓冲区存储着诊断信息文本串。 | +| BufferLength | MessageText的长度。 | +| TextLengthPtr | **输出参数**:指向缓冲区的指针,返回MessageText中的字节总数。如果返回字节数大于BufferLength,则MessageText中的诊断信息文本被截断成BufferLength减去NULL结尾字符的长度。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +SQLGetDiagRec不发布自己的诊断记录。它用下列返回值来报告它自己的执行结果: + +- SQL_SUCCESS:函数成功返回诊断信息。 +- SQL_SUCCESS_WITH_INFO:MessageText太小以致不能容纳所请求的诊断信息。没有诊断记录生成。 +- SQL_INVALID_HANDLE:由HandType和Handle所指出的句柄是不合法句柄。 +- SQL_ERROR:RecNumber小于等于0或BufferLength小于0。 + +如果调用ODBC函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO,可调用SQLGetDiagRec返回诊断信息值SQLSTATE,SQLSTATE值的如下表。 + +**表 2** SQLSTATE值 + +| SQLSATATE | 错误 | 描述 | +| :-------- | :------------------- | :----------------------------------------------------------- | +| HY000 | 一般错误 | 未定义特定的SQLSTATE所产生的一个错误。 | +| HY001 | 内存分配错误 | 驱动程序不能分配所需要的内存来支持函数的执行或完成。 | +| HY008 | 取消操作 | 调用SQLCancel取消执行语句后,依然在StatementHandle上调用函数。 | +| HY010 | 函数系列错误 | 在为执行中的所有数据参数或列发送数据前就调用了执行函数。 | +| HY013 | 内存管理错误 | 不能处理函数调用,可能由当前内存条件差引起。 | +| HYT01 | 连接超时 | 数据源响应请求之前,连接超时。 | +| IM001 | 驱动程序不支持此函数 | 调用了StatementHandle相关的驱动程序不支持的函数。 | + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-2-SQLAllocConnect.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-2-SQLAllocConnect.md new file mode 100644 index 00000000..4297a0a7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-2-SQLAllocConnect.md @@ -0,0 +1,10 @@ +--- +title: SQLAllocConnect +summary: SQLAllocConnect +author: Guo Huan +date: 2021-05-17 +--- + +# SQLAllocConnect + +在ODBC 3.x版本中,ODBC 2.x的函数SQLAllocConnect已被SQLAllocHandle代替。有关详细信息请参阅[SQLAllocHandle](2-3-SQLAllocHandle.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-20-SQLSetConnectAttr.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-20-SQLSetConnectAttr.md new file mode 100644 index 00000000..e655c49f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-20-SQLSetConnectAttr.md @@ -0,0 +1,47 @@ +--- +title: SQLSetConnectAttr +summary: SQLSetConnectAttr +author: Guo Huan +date: 2021-05-17 +--- + +# SQLSetConnectAttr + +## 功能描述 + +设置控制连接各方面的属性。 + +## 原型 + +``` +SQLRETURN SQLSetConnectAttr(SQLHDBC ConnectionHandle + SQLINTEGER Attribute, + SQLPOINTER ValuePtr, + SQLINTEGER StringLength); +``` + +## 参数 + +**表 1** SQLSetConnectAttr参数 + +| **关键字** | **参数说明** | +| :--------------- | :----------------------------------------------------------- | +| ConnectionHandle | 连接句柄。 | +| Attribute | 设置属性。 | +| ValuePtr | 指向对应Attribute的值。依赖于Attribute的值,ValuePtr是32位无符号整型值或指向以空结束的字符串。注意,如果ValuePtr参数是驱动程序指定值。ValuePtr可能是有符号的整数。 | +| StringLength | 如果ValuePtr指向字符串或二进制缓冲区,这个参数是*ValuePtr长度,如果ValuePtr指向整型,忽略StringLength。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +当SQLSetConnectAttr的返回值为SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过借助SQL_HANDLE_DBC的HandleType和ConnectionHandle的Handle,调用SQLGetDiagRec可得到相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-21-SQLSetEnvAttr.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-21-SQLSetEnvAttr.md new file mode 100644 index 00000000..be6a8bc5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-21-SQLSetEnvAttr.md @@ -0,0 +1,47 @@ +--- +title: SQLSetEnvAttr +summary: SQLSetEnvAttr +author: Guo Huan +date: 2021-05-17 +--- + +# SQLSetEnvAttr + +## 功能描述 + +设置控制环境各方面的属性。 + +## 原型 + +``` +SQLRETURN SQLSetEnvAttr(SQLHENV EnvironmentHandle + SQLINTEGER Attribute, + SQLPOINTER ValuePtr, + SQLINTEGER StringLength); +``` + +## 参数 + +**表 1** SQLSetEnvAttr参数 + +| **关键字** | **参数说明** | +| :---------------- | :----------------------------------------------------------- | +| EnvironmentHandle | 环境句柄。 | +| Attribute | 需设置的环境属性,可为如下值:
- SQL_ATTR_ODBC_VERSION:指定ODBC版本。
- SQL_CONNECTION_POOLING:连接池属性。
- SQL_OUTPUT_NTS:指明驱动器返回字符串的形式。 | +| ValuePtr | 指向对应Attribute的值。依赖于Attribute的值,ValuePtr可能是32位整型值,或为以空结束的字符串。 | +| StringLength | 如果ValuePtr指向字符串或二进制缓冲区,这个参数是*ValuePtr长度,如果ValuePtr指向整型,忽略StringLength。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +当SQLSetEnvAttr的返回值为SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过借助SQL_HANDLE_ENV的HandleType和EnvironmentHandle的Handle,调用SQLGetDiagRec可得到相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-22-SQLSetStmtAttr.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-22-SQLSetStmtAttr.md new file mode 100644 index 00000000..2be11f81 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-22-SQLSetStmtAttr.md @@ -0,0 +1,47 @@ +--- +title: SQLSetStmtAttr +summary: SQLSetStmtAttr +author: Guo Huan +date: 2021-05-17 +--- + +# SQLSetStmtAttr + +## 功能描述 + +设置相关语句的属性。 + +## 原型 + +``` +SQLRETURN SQLSetStmtAttr(SQLHSTMT StatementHandle + SQLINTEGER Attribute, + SQLPOINTER ValuePtr, + SQLINTEGER StringLength); +``` + +## 参数 + +**表 1** SQLSetStmtAttr参数 + +| **关键字** | **参数说明** | +| :-------------- | :----------------------------------------------------------- | +| StatementHandle | 语句句柄。 | +| Attribute | 需设置的属性。 | +| ValuePtr | 指向对应Attribute的值。依赖于Attribute的值,ValuePtr可能是32位无符号整型值,或指向以空结束的字符串,二进制缓冲区,或者驱动定义值。注意,如果ValuePtr参数是驱动程序指定值。ValuePtr可能是有符号的整数。 | +| StringLength | 如果ValuePtr指向字符串或二进制缓冲区,这个参数是*ValuePtr长度,如果ValuePtr指向整型,忽略StringLength。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +当SQLSetStmtAttr的返回值为SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过借助SQL_HANDLE_STMT的HandleType和StatementHandle的Handle,调用SQLGetDiagRec可得到相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-23-Examples.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-23-Examples.md new file mode 100644 index 00000000..5c39c932 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-23-Examples.md @@ -0,0 +1,347 @@ +--- +title: 示例 +summary: 示例 +author: Guo Huan +date: 2021-05-17 +--- + +# 示例 + +## 常用功能示例代码 + +```c +// 此示例演示如何通过ODBC方式获取MogDB中的数据。 +// DBtest.c (compile with: libodbc.so) +#include +#include +#include +#ifdef WIN32 +#include +#endif +SQLHENV V_OD_Env; // Handle ODBC environment +SQLHSTMT V_OD_hstmt; // Handle statement +SQLHDBC V_OD_hdbc; // Handle connection +char typename[100]; +SQLINTEGER value = 100; +SQLINTEGER V_OD_erg,V_OD_buffer,V_OD_err,V_OD_id; +int main(int argc,char *argv[]) +{ + // 1. 申请环境句柄 + V_OD_erg = SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&V_OD_Env); + if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) + { + printf("Error AllocHandle\n"); + exit(0); + } + // 2. 设置环境属性(版本信息) + SQLSetEnvAttr(V_OD_Env, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0); + // 3. 申请连接句柄 + V_OD_erg = SQLAllocHandle(SQL_HANDLE_DBC, V_OD_Env, &V_OD_hdbc); + if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) + { + SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); + exit(0); + } + // 4. 设置连接属性 + SQLSetConnectAttr(V_OD_hdbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_ON, 0); + // 5. 连接数据源,这里的“userName”与“password”分别表示连接数据库的用户名和用户密码,请根据实际情况修改。 + // 如果odbc.ini文件中已经配置了用户名密码,那么这里可以留空("");但是不建议这么做,因为一旦odbc.ini权限管理不善,将导致数据库用户密码泄露。 + V_OD_erg = SQLConnect(V_OD_hdbc, (SQLCHAR*) "mogdb", SQL_NTS, + (SQLCHAR*) "userName", SQL_NTS, (SQLCHAR*) "password", SQL_NTS); + if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO)) + { + printf("Error SQLConnect %d\n",V_OD_erg); + SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); + exit(0); + } + printf("Connected !\n"); + // 6. 设置语句属性 + SQLSetStmtAttr(V_OD_hstmt,SQL_ATTR_QUERY_TIMEOUT,(SQLPOINTER *)3,0); + // 7. 申请语句句柄 + SQLAllocHandle(SQL_HANDLE_STMT, V_OD_hdbc, &V_OD_hstmt); + // 8. 直接执行SQL语句。 + SQLExecDirect(V_OD_hstmt,"drop table IF EXISTS customer_t1",SQL_NTS); + SQLExecDirect(V_OD_hstmt,"CREATE TABLE customer_t1(c_customer_sk INTEGER, c_customer_name VARCHAR(32));",SQL_NTS); + SQLExecDirect(V_OD_hstmt,"insert into customer_t1 values(25,li)",SQL_NTS); + // 9. 准备执行 + SQLPrepare(V_OD_hstmt,"insert into customer_t1 values(?)",SQL_NTS); + // 10. 绑定参数 + SQLBindParameter(V_OD_hstmt,1,SQL_PARAM_INPUT,SQL_C_SLONG,SQL_INTEGER,0,0, + &value,0,NULL); + // 11. 执行准备好的语句 + SQLExecute(V_OD_hstmt); + SQLExecDirect(V_OD_hstmt,"select id from testtable",SQL_NTS); + // 12. 获取结果集某一列的属性 + SQLColAttribute(V_OD_hstmt,1,SQL_DESC_TYPE,typename,100,NULL,NULL); + printf("SQLColAtrribute %s\n",typename); + // 13. 绑定结果集 + SQLBindCol(V_OD_hstmt,1,SQL_C_SLONG, (SQLPOINTER)&V_OD_buffer,150, + (SQLLEN *)&V_OD_err); + // 14. 通过SQLFetch取结果集中数据 + V_OD_erg=SQLFetch(V_OD_hstmt); + // 15. 通过SQLGetData获取并返回数据。 + while(V_OD_erg != SQL_NO_DATA) + { + SQLGetData(V_OD_hstmt,1,SQL_C_SLONG,(SQLPOINTER)&V_OD_id,0,NULL); + printf("SQLGetData ----ID = %d\n",V_OD_id); + V_OD_erg=SQLFetch(V_OD_hstmt); + }; + printf("Done !\n"); + // 16. 断开数据源连接并释放句柄资源 + SQLFreeHandle(SQL_HANDLE_STMT,V_OD_hstmt); + SQLDisconnect(V_OD_hdbc); + SQLFreeHandle(SQL_HANDLE_DBC,V_OD_hdbc); + SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env); + return(0); + } +``` + +
+ +## 批量绑定示例代码 + +```c +/********************************************************************** +* 请在数据源中打开UseBatchProtocol,同时指定数据库中参数support_batch_bind +* 为on +* CHECK_ERROR的作用是检查并打印错误信息。 +* 此示例将与用户交互式获取DSN、模拟的数据量,忽略的数据量,并将最终数据入库到test_odbc_batch_insert中 +***********************************************************************/ +#include +#include +#include +#include +#include + +#include "util.c" + +void Exec(SQLHDBC hdbc, SQLCHAR* sql) +{ + SQLRETURN retcode; // Return status + SQLHSTMT hstmt = SQL_NULL_HSTMT; // Statement handle + SQLCHAR loginfo[2048]; + + // Allocate Statement Handle + retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt); + CHECK_ERROR(retcode, "SQLAllocHandle(SQL_HANDLE_STMT)", + hstmt, SQL_HANDLE_STMT); + + // Prepare Statement + retcode = SQLPrepare(hstmt, (SQLCHAR*) sql, SQL_NTS); + sprintf((char*)loginfo, "SQLPrepare log: %s", (char*)sql); + CHECK_ERROR(retcode, loginfo, hstmt, SQL_HANDLE_STMT); + + // Execute Statement + retcode = SQLExecute(hstmt); + sprintf((char*)loginfo, "SQLExecute stmt log: %s", (char*)sql); + CHECK_ERROR(retcode, loginfo, hstmt, SQL_HANDLE_STMT); + + // Free Handle + retcode = SQLFreeHandle(SQL_HANDLE_STMT, hstmt); + sprintf((char*)loginfo, "SQLFreeHandle stmt log: %s", (char*)sql); + CHECK_ERROR(retcode, loginfo, hstmt, SQL_HANDLE_STMT); +} + +int main () +{ + SQLHENV henv = SQL_NULL_HENV; + SQLHDBC hdbc = SQL_NULL_HDBC; + int batchCount = 1000; + SQLLEN rowsCount = 0; + int ignoreCount = 0; + + SQLRETURN retcode; + SQLCHAR dsn[1024] = {'\0'}; + SQLCHAR loginfo[2048]; + + // 交互获取数据源名称 + getStr("Please input your DSN", (char*)dsn, sizeof(dsn), 'N'); + // 交互获取批量绑定的数据量 + getInt("batchCount", &batchCount, 'N', 1); + do + { + // 交互获取批量绑定的数据中,不要入库的数据量 + getInt("ignoreCount", &ignoreCount, 'N', 1); + if (ignoreCount > batchCount) + { + printf("ignoreCount(%d) should be less than batchCount(%d)\n", ignoreCount, batchCount); + } + }while(ignoreCount > batchCount); + + retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv); + CHECK_ERROR(retcode, "SQLAllocHandle(SQL_HANDLE_ENV)", + henv, SQL_HANDLE_ENV); + + // Set ODBC Verion + retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, + (SQLPOINTER*)SQL_OV_ODBC3, 0); + CHECK_ERROR(retcode, "SQLSetEnvAttr(SQL_ATTR_ODBC_VERSION)", + henv, SQL_HANDLE_ENV); + + // Allocate Connection + retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc); + CHECK_ERROR(retcode, "SQLAllocHandle(SQL_HANDLE_DBC)", + henv, SQL_HANDLE_DBC); + + // Set Login Timeout + retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0); + CHECK_ERROR(retcode, "SQLSetConnectAttr(SQL_LOGIN_TIMEOUT)", + hdbc, SQL_HANDLE_DBC); + + // Set Auto Commit + retcode = SQLSetConnectAttr(hdbc, SQL_ATTR_AUTOCOMMIT, + (SQLPOINTER)(1), 0); + CHECK_ERROR(retcode, "SQLSetConnectAttr(SQL_ATTR_AUTOCOMMIT)", + hdbc, SQL_HANDLE_DBC); + + // Connect to DSN + sprintf(loginfo, "SQLConnect(DSN:%s)", dsn); + retcode = SQLConnect(hdbc, (SQLCHAR*) dsn, SQL_NTS, + (SQLCHAR*) NULL, 0, NULL, 0); + CHECK_ERROR(retcode, loginfo, hdbc, SQL_HANDLE_DBC); + + // init table info. + Exec(hdbc, "drop table if exists test_odbc_batch_insert"); + Exec(hdbc, "create table test_odbc_batch_insert(id int primary key, col varchar2(50))"); + + // 下面的代码根据用户输入的数据量,构造出将要入库的数据: + { + SQLRETURN retcode; + SQLHSTMT hstmtinesrt = SQL_NULL_HSTMT; + int i; + SQLCHAR *sql = NULL; + SQLINTEGER *ids = NULL; + SQLCHAR *cols = NULL; + SQLLEN *bufLenIds = NULL; + SQLLEN *bufLenCols = NULL; + SQLUSMALLINT *operptr = NULL; + SQLUSMALLINT *statusptr = NULL; + SQLULEN process = 0; + + // 这里是按列构造,每个字段的内存连续存放在一起。 + ids = (SQLINTEGER*)malloc(sizeof(ids[0]) * batchCount); + cols = (SQLCHAR*)malloc(sizeof(cols[0]) * batchCount * 50); + // 这里是每个字段中,每一行数据的内存长度。 + bufLenIds = (SQLLEN*)malloc(sizeof(bufLenIds[0]) * batchCount); + bufLenCols = (SQLLEN*)malloc(sizeof(bufLenCols[0]) * batchCount); + // 该行是否需要被处理,SQL_PARAM_IGNORE 或 SQL_PARAM_PROCEED + operptr = (SQLUSMALLINT*)malloc(sizeof(operptr[0]) * batchCount); + memset(operptr, 0, sizeof(operptr[0]) * batchCount); + // 该行的处理结果。 + // 注:由于数据库中处理方式是同一语句隶属同一事务中,所以如果出错,那么待处理数据都将是出错的,并不会部分入库。 + statusptr = (SQLUSMALLINT*)malloc(sizeof(statusptr[0]) * batchCount); + memset(statusptr, 88, sizeof(statusptr[0]) * batchCount); + + if (NULL == ids || NULL == cols || NULL == bufLenCols || NULL == bufLenIds) + { + fprintf(stderr, "FAILED:\tmalloc data memory failed\n"); + goto exit; + } + + for (int i = 0; i < batchCount; i++) + { + ids[i] = i; + sprintf(cols + 50 * i, "column test value %d", i); + bufLenIds[i] = sizeof(ids[i]); + bufLenCols[i] = strlen(cols + 50 * i); + operptr[i] = (i < ignoreCount) ? SQL_PARAM_IGNORE : SQL_PARAM_PROCEED; + } + + // Allocate Statement Handle + retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtinesrt); + CHECK_ERROR(retcode, "SQLAllocHandle(SQL_HANDLE_STMT)", + hstmtinesrt, SQL_HANDLE_STMT); + + // Prepare Statement + sql = (SQLCHAR*)"insert into test_odbc_batch_insert values(?, ?)"; + retcode = SQLPrepare(hstmtinesrt, (SQLCHAR*) sql, SQL_NTS); + sprintf((char*)loginfo, "SQLPrepare log: %s", (char*)sql); + CHECK_ERROR(retcode, loginfo, hstmtinesrt, SQL_HANDLE_STMT); + + retcode = SQLSetStmtAttr(hstmtinesrt, SQL_ATTR_PARAMSET_SIZE, (SQLPOINTER)batchCount, sizeof(batchCount)); + CHECK_ERROR(retcode, "SQLSetStmtAttr", hstmtinesrt, SQL_HANDLE_STMT); + + retcode = SQLBindParameter(hstmtinesrt, 1, SQL_PARAM_INPUT, SQL_C_SLONG, SQL_INTEGER, sizeof(ids[0]), 0,&(ids[0]), 0, bufLenIds); + CHECK_ERROR(retcode, "SQLBindParameter for id", hstmtinesrt, SQL_HANDLE_STMT); + + retcode = SQLBindParameter(hstmtinesrt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 50, cols, 50, bufLenCols); + CHECK_ERROR(retcode, "SQLBindParameter for cols", hstmtinesrt, SQL_HANDLE_STMT); + + retcode = SQLSetStmtAttr(hstmtinesrt, SQL_ATTR_PARAMS_PROCESSED_PTR, (SQLPOINTER)&process, sizeof(process)); + CHECK_ERROR(retcode, "SQLSetStmtAttr for SQL_ATTR_PARAMS_PROCESSED_PTR", hstmtinesrt, SQL_HANDLE_STMT); + + retcode = SQLSetStmtAttr(hstmtinesrt, SQL_ATTR_PARAM_STATUS_PTR, (SQLPOINTER)statusptr, sizeof(statusptr[0]) * batchCount); + CHECK_ERROR(retcode, "SQLSetStmtAttr for SQL_ATTR_PARAM_STATUS_PTR", hstmtinesrt, SQL_HANDLE_STMT); + + retcode = SQLSetStmtAttr(hstmtinesrt, SQL_ATTR_PARAM_OPERATION_PTR, (SQLPOINTER)operptr, sizeof(operptr[0]) * batchCount); + CHECK_ERROR(retcode, "SQLSetStmtAttr for SQL_ATTR_PARAM_OPERATION_PTR", hstmtinesrt, SQL_HANDLE_STMT); + + retcode = SQLExecute(hstmtinesrt); + sprintf((char*)loginfo, "SQLExecute stmt log: %s", (char*)sql); + CHECK_ERROR(retcode, loginfo, hstmtinesrt, SQL_HANDLE_STMT); + + retcode = SQLRowCount(hstmtinesrt, &rowsCount); + CHECK_ERROR(retcode, "SQLRowCount execution", hstmtinesrt, SQL_HANDLE_STMT); + + if (rowsCount != (batchCount - ignoreCount)) + { + sprintf(loginfo, "(batchCount - ignoreCount)(%d) != rowsCount(%d)", (batchCount - ignoreCount), rowsCount); + CHECK_ERROR(SQL_ERROR, loginfo, NULL, SQL_HANDLE_STMT); + } + else + { + sprintf(loginfo, "(batchCount - ignoreCount)(%d) == rowsCount(%d)", (batchCount - ignoreCount), rowsCount); + CHECK_ERROR(SQL_SUCCESS, loginfo, NULL, SQL_HANDLE_STMT); + } + + // check row number returned + if (rowsCount != process) + { + sprintf(loginfo, "process(%d) != rowsCount(%d)", process, rowsCount); + CHECK_ERROR(SQL_ERROR, loginfo, NULL, SQL_HANDLE_STMT); + } + else + { + sprintf(loginfo, "process(%d) == rowsCount(%d)", process, rowsCount); + CHECK_ERROR(SQL_SUCCESS, loginfo, NULL, SQL_HANDLE_STMT); + } + + for (int i = 0; i < batchCount; i++) + { + if (i < ignoreCount) + { + if (statusptr[i] != SQL_PARAM_UNUSED) + { + sprintf(loginfo, "statusptr[%d](%d) != SQL_PARAM_UNUSED", i, statusptr[i]); + CHECK_ERROR(SQL_ERROR, loginfo, NULL, SQL_HANDLE_STMT); + } + } + else if (statusptr[i] != SQL_PARAM_SUCCESS) + { + sprintf(loginfo, "statusptr[%d](%d) != SQL_PARAM_SUCCESS", i, statusptr[i]); + CHECK_ERROR(SQL_ERROR, loginfo, NULL, SQL_HANDLE_STMT); + } + } + + retcode = SQLFreeHandle(SQL_HANDLE_STMT, hstmtinesrt); + sprintf((char*)loginfo, "SQLFreeHandle hstmtinesrt"); + CHECK_ERROR(retcode, loginfo, hstmtinesrt, SQL_HANDLE_STMT); + } + + +exit: + printf ("\nComplete.\n"); + + // Connection + if (hdbc != SQL_NULL_HDBC) { + SQLDisconnect(hdbc); + SQLFreeHandle(SQL_HANDLE_DBC, hdbc); + } + + // Environment + if (henv != SQL_NULL_HENV) + SQLFreeHandle(SQL_HANDLE_ENV, henv); + + return 0; +} +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-3-SQLAllocHandle.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-3-SQLAllocHandle.md new file mode 100644 index 00000000..50cad31f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-3-SQLAllocHandle.md @@ -0,0 +1,45 @@ +--- +title: SQLAllocHandle +summary: SQLAllocHandle +author: Guo Huan +date: 2021-05-17 +--- + +# SQLAllocHandle + +## 功能描述 + +分配环境、连接、语句或描述符的句柄,它替代了ODBC 2.x函数SQLAllocEnv、SQLAllocConnect及SQLAllocStmt。 + +## 原型 + +```c +SQLRETURN SQLAllocHandle(SQLSMALLINT HandleType, + SQLHANDLE InputHandle, + SQLHANDLE *OutputHandlePtr); +``` + +## 参数 + +**表 1** SQLAllocHandle参数 + +| **关键字** | **参数说明** | +| :-------------- | :----------------------------------------------------------- | +| HandleType | 由SQLAllocHandle分配的句柄类型。必须为下列值之一:
- SQL_HANDLE_ENV(环境句柄)
- SQL_HANDLE_DBC(连接句柄)
- SQL_HANDLE_STMT(语句句柄)
- SQL_HANDLE_DESC(描述句柄)
申请句柄顺序为,先申请环境句柄,再申请连接句柄,最后申请语句句柄,后申请的句柄都要依赖它前面申请的句柄。 | +| InputHandle | 将要分配的新句柄的类型。
- 如果HandleType为SQL_HANDLE_ENV,则这个值为SQL_NULL_HANDLE。
- 如果HandleType为SQL_HANDLE_DBC,则这一定是一个环境句柄。
- 如果HandleType为SQL_HANDLE_STMT或SQL_HANDLE_DESC,则它一定是一个连接句柄。 | +| OutputHandlePtr | **输出参数**:一个缓冲区的指针,此缓冲区以新分配的数据结构存放返回的句柄。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +当分配的句柄并非环境句柄时,如果SQLAllocHandle返回的值为SQL_ERROR,则它会将OutputHandlePtr的值设置为SQL_NULL_HDBC、SQL_NULL_HSTMT或SQL_NULL_HDESC。之后,通过调用带有适当参数的SQLGetDiagRec,其中HandleType和Handle被设置为IntputHandle的值,可得到相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-4-SQLAllocStmt.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-4-SQLAllocStmt.md new file mode 100644 index 00000000..c22aaf63 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-4-SQLAllocStmt.md @@ -0,0 +1,10 @@ +--- +title: SQLAllocStmt +summary: SQLAllocStmt +author: Guo Huan +date: 2021-05-17 +--- + +# SQLAllocStmt + +在ODBC 3.x版本中,ODBC 2.x的函数SQLAllocStmt已被SQLAllocHandle代替。有关详细信息请参阅[SQLAllocHandle](2-3-SQLAllocHandle.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-5-SQLBindCol.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-5-SQLBindCol.md new file mode 100644 index 00000000..c229abcc --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-5-SQLBindCol.md @@ -0,0 +1,51 @@ +--- +title: SQLBindCol +summary: SQLBindCol +author: Guo Huan +date: 2021-05-17 +--- + +# SQLBindCol + +## 功能描述 + +将应用程序数据缓冲区绑定到结果集的列中。 + +## 原型 + +```c +SQLRETURN SQLBindCol(SQLHSTMT StatementHandle, + SQLUSMALLINT ColumnNumber, + SQLSMALLINT TargetType, + SQLPOINTER TargetValuePtr, + SQLLEN BufferLength, + SQLLEN *StrLen_or_IndPtr); +``` + +## 参数 + +**表 1** SQLBindCol参数 + +| **关键字** | **参数说明** | +| :--------------- | :----------------------------------------------------------- | +| StatementHandle | 语句句柄。 | +| ColumnNumber | 要绑定结果集的列号。起始列号为0,以递增的顺序计算列号,第0列是书签列。若未设置书签页,则起始列号为1。 | +| TargetType | 缓冲区中C数据类型的标识符。 | +| TargetValuePtr | **输出参数**:指向与列绑定的数据缓冲区的指针。SQLFetch函数返回这个缓冲区中的数据。如果此参数为一个空指针,则StrLen_or_IndPtr是一个有效值。 | +| BufferLength | TargetValuePtr指向缓冲区的长度,以字节为单位。 | +| StrLen_or_IndPtr | **输出参数**:缓冲区的长度或指示器指针。若为空值,则未使用任何长度或指示器值。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +当SQLBindCol返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-6-SQLBindParameter.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-6-SQLBindParameter.md new file mode 100644 index 00000000..704690c0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-6-SQLBindParameter.md @@ -0,0 +1,59 @@ +--- +title: SQLBindParameter +summary: SQLBindParameter +author: Guo Huan +date: 2021-05-17 +--- + +# SQLBindParameter + +## 功能描述 + +将一条SQL语句中的一个参数标志和一个缓冲区绑定起来。 + +## 原型 + +```c +SQLRETURN SQLBindParameter(SQLHSTMT StatementHandle, + SQLUSMALLINT ParameterNumber, + SQLSMALLINT InputOutputType, + SQLSMALLINT ValuetType, + SQLSMALLINT ParameterType, + SQLULEN ColumnSize, + SQLSMALLINT DecimalDigits, + SQLPOINTER ParameterValuePtr, + SQLLEN BufferLength, + SQLLEN *StrLen_or_IndPtr); +``` + +## 参数 + +**表 1** SQLBindParameter + +| **关键词** | **参数说明** | +| :---------------- | :----------------------------------------------------------- | +| StatementHandle | 语句句柄。 | +| ParameterNumber | 参数序号,起始为1,依次递增。 | +| InputOutputType | 输入输出参数类型。 | +| ValueType | 参数的C数据类型。 | +| ParameterType | 参数的SQL数据类型。 | +| ColumnSize | 列的大小或相应参数标记的表达式。 | +| DecimalDigits | 列的十进制数字或相应参数标记的表达式。 | +| ParameterValuePtr | 指向存储参数数据缓冲区的指针。 | +| BufferLength | ParameterValuePtr指向缓冲区的长度,以字节为单位。 | +| StrLen_or_IndPtr | 缓冲区的长度或指示器指针。若为空值,则未使用任何长度或指示器值。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +当SQLBindParameter返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-7-SQLColAttribute.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-7-SQLColAttribute.md new file mode 100644 index 00000000..db7012cb --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-7-SQLColAttribute.md @@ -0,0 +1,53 @@ +--- +title: SQLColAttribute +summary: SQLColAttribute +author: Guo Huan +date: 2021-05-17 +--- + +# SQLColAttribute + +## 功能描述 + +返回结果集中一列的描述符信息。 + +## 原型 + +```c +SQLRETURN SQLColAttibute(SQLHSTMT StatementHandle, + SQLUSMALLINT ColumnNumber, + SQLUSMALLINT FieldIdentifier, + SQLPOINTER CharacterAtrriburePtr, + SQLSMALLINT BufferLength, + SQLSMALLINT *StringLengthPtr, + SQLLEN *NumericAttributePtr); +``` + +## 参数 + +**表 1** SQLColAttribute参数 + +| **关键字** | **参数说明** | +| :-------------------- | :----------------------------------------------------------- | +| StatementHandle | 语句句柄。 | +| ColumnNumber | 要检索字段的列号,起始为1,依次递增。 | +| FieldIdentifier | IRD中ColumnNumber行的字段。 | +| CharacterAttributePtr | **输出参数**:一个缓冲区指针,返回FieldIdentifier字段值。 | +| BufferLength | - 如果FieldIdentifier是一个ODBC定义的字段,而且CharacterAttributePtr指向一个字符串或二进制缓冲区,则此参数为该缓冲区的长度。
- 如果FieldIdentifier是一个ODBC定义的字段,而且CharacterAttributePtr指向一个整数,则会忽略该字段。 | +| StringLengthPtr | **输出参数**:缓冲区指针,存放*CharacterAttributePtr中字符类型数据的字节总数,对于非字符类型,忽略BufferLength的值。 | +| NumericAttributePtr | **输出参数**:指向一个整型缓冲区的指针,返回IRD中ColumnNumber行FieldIdentifier字段的值。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +当SQLColAttribute返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数设置为SQL_HANDLE_STMT和StatementHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-8-SQLConnect.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-8-SQLConnect.md new file mode 100644 index 00000000..4225c8a4 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-8-SQLConnect.md @@ -0,0 +1,54 @@ +--- +title: SQLConnect +summary: SQLConnect +author: Guo Huan +date: 2021-05-17 +--- + +# SQLConnect + +## 功能描述 + +在驱动程序和数据源之间建立连接。连接上数据源之后,可以通过连接句柄访问到所有有关连接数据源的信息,包括程序运行状态、事务处理状态和错误信息。 + +## 原型 + +``` +SQLRETURN SQLConnect(SQLHDBC ConnectionHandle, + SQLCHAR *ServerName, + SQLSMALLINT NameLength1, + SQLCHAR *UserName, + SQLSMALLINT NameLength2, + SQLCHAR *Authentication, + SQLSMALLINT NameLength3); +``` + +## 参数 + +**表 1** SQLConnect参数 + +| **关键字** | **参数说明** | +| :--------------- | :--------------------------------- | +| ConnectionHandle | 连接句柄,通过SQLAllocHandle获得。 | +| ServerName | 要连接数据源的名称。 | +| NameLength1 | ServerName的长度。 | +| UserName | 数据源中数据库用户名。 | +| NameLength2 | UserName的长度。 | +| Authentication | 数据源中数据库用户密码。 | +| NameLength3 | Authentication的长度。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 +- SQL_STILL_EXECUTING:表示语句正在执行。 + +## 注意事项 + +当调用SQLConnect函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数设置为SQL_HANDLE_DBC和ConnectionHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-9-SQLDisconnect.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-9-SQLDisconnect.md new file mode 100644 index 00000000..4b6cd33b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/3-development-based-on-odbc/6-ODBC/2-9-SQLDisconnect.md @@ -0,0 +1,41 @@ +--- +title: SQLDisconnect +summary: SQLDisconnect +author: Guo Huan +date: 2021-05-17 +--- + +# SQLDisconnect + +## 功能描述 + +关闭一个与特定连接句柄相关的连接。 + +## 原型 + +``` +SQLRETURN SQLDisconnect(SQLHDBC ConnectionHandle); +``` + +## 参数 + +**表 1** SQLDisconnect参数 + +| **关键字** | **参数说明** | +| :--------------- | :--------------------------------- | +| ConnectionHandle | 连接句柄,通过SQLAllocHandle获得。 | + +## 返回值 + +- SQL_SUCCESS:表示调用正确。 +- SQL_SUCCESS_WITH_INFO:表示会有一些警告信息。 +- SQL_ERROR:表示比较严重的错误,如:内存分配失败、建立连接失败等。 +- SQL_INVALID_HANDLE:表示调用无效句柄。其他API的返回值同理。 + +## 注意事项 + +当调用SQLDisconnect函数返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,通过调用SQLGetDiagRec函数,并将HandleType和Handle参数设置为SQL_HANDLE_DBC和ConnectionHandle,可得到一个相关的SQLSTATE值,通过SQLSTATE值可以查出调用此函数的具体信息。 + +## 示例 + +参见:[示例](2-23-Examples.md) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/1-database-connection-control-functions-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/1-database-connection-control-functions-overview.md new file mode 100644 index 00000000..5de97fc9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/1-database-connection-control-functions-overview.md @@ -0,0 +1,10 @@ +--- +title: 说明 +summary: 说明 +author: Guo Huan +date: 2021-05-17 +--- + +# 说明 + +数据库连接控制函数控制与MogDB服务器链接的事情。一个应用程序一次可以与多个服务器建立链接,如一个客户端链接多个数据库的场景。每个链接都是用一个从函数PQconnectdb、PQconnectdbParams或PQsetdbLogin获得的PGconn对象表示。注意,这些函数总是返回一个非空的对象指针,除非内存分配失败,会返回一个空的指针。链接建立的接口保存在PGconn对象中,可以调用PQstatus函数来检查一下返回值看看连接是否成功。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/10-PQstatus.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/10-PQstatus.md new file mode 100644 index 00000000..0a9d5f9d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/10-PQstatus.md @@ -0,0 +1,64 @@ +--- +title: PQstatus +summary: PQstatus +author: Guo Huan +date: 2021-05-17 +--- + +# PQstatus + +## 功能描述 + +返回链接的状态。 + +## 原型 + +``` +ConnStatusType PQstatus(const PGconn *conn); +``` + +## 参数 + +**表 1** PQstatus参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| conn | 指向包含链接的对象指针。 | + +## 返回值 + +ConnStatusType:链接状态的枚举,包括: + +``` +CONNECTION_STARTED +等待进行连接。 + +CONNECTION_MADE +连接成功;等待发送。 + +CONNECTION_AWAITING_RESPONSE +等待来自服务器的响应。 + +CONNECTION_AUTH_OK +已收到认证;等待后端启动结束。 + +CONNECTION_SSL_STARTUP +协商SSL加密。 + +CONNECTION_SETENV +协商环境驱动的参数设置。 + +CONNECTION_OK +链接正常。 + +CONNECTION_BAD +链接故障。 +``` + +## 注意事项 + +状态可以是多个值之一。但是,在异步连接过程之外只能看到其中两个:CONNECTION_OK和CONNECTION_BAD。与数据库的良好连接状态为CONNECTION_OK。状态表示连接尝试失败CONNECTION_BAD。通常,“正常”状态将一直保持到PQfinish,但通信失败可能会导致状态CONNECTION_BAD过早变为。在这种情况下,应用程序可以尝试通过调用进行恢复PQreset。 + +## 示例 + +请参见[示例](../../libpq-example.md)章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/2-PQconnectdbParams.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/2-PQconnectdbParams.md new file mode 100644 index 00000000..85f11e46 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/2-PQconnectdbParams.md @@ -0,0 +1,42 @@ +--- +title: PQconnectdbParams +summary: PQconnectdbParams +author: Guo Huan +date: 2021-05-17 +--- + +# PQconnectdbParams + +## 功能描述 + +与数据库服务器建立一个新的连接。 + +## 原型 + +``` +PGconn *PQconnectdbParams(const char * const *keywords, + const char * const *values, + int expand_dbname); +``` + +## 参数 + +**表 1** PQconnectdbParams参数 + +| **关键字** | **参数说明** | +| :------------ | :----------------------------------------------------------- | +| keywords | 定义为一个字符串的数组,每个都成为一个关键字。 | +| values | 给每个关键字一个值。 | +| expand_dbname | 当expand_dbname是非零的时,允许将dbname的关键字值看做一个连接字符串。只有第一个出现的dbname是这样展开的,任何随后的dbname值作为纯数据库名处理。 | + +## 返回值 + +PGconn *:指向包含链接的对象指针,内存在函数内部申请。 + +## 注意事项 + +这个函数用从两个NULL结束的数组中来的参数打开一个新的数据库连接。与PQsetdbLogin不同的是,可以不必更换函数签名(名字)就可以扩展参数集,所以建议应用程序中使用这个函数(或者它的类似的非阻塞变种PQconnectStartParams和PQconnectPoll)。 + +## 示例 + +请参见[示例](../../libpq-example.md)章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/3-PQconnectdb.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/3-PQconnectdb.md new file mode 100644 index 00000000..16306e3c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/3-PQconnectdb.md @@ -0,0 +1,39 @@ +--- +title: PQconnectdb +summary: PQconnectdb +author: Guo Huan +date: 2021-05-17 +--- + +# PQconnectdb + +## 功能描述 + +与数据库服务器建立一个新的连接。 + +## 原型 + +``` +PGconn *PQconnectdb(const char *conninfo); +``` + +## 参数 + +**表 1** PQconnectdb参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------------------------- | +| conninfo | 链接字符串,字符串中的字段见链接字符章节。 | + +## 返回值 + +PGconn *:指向包含链接的对象指针,内存在函数内部申请。 + +## 注意事项 + +- 这个函数用从一个字符串conninfo来的参数与数据库打开一个新的链接。 +- 传入的参数可以为空,表明使用所有缺省的参数,或者可以包含一个或更多个用空白间隔的参数设置,或者它可以包含一个URL。 + +## 示例 + +请参见[示例](../../libpq-example.md)章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/4-PQconninfoParse.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/4-PQconninfoParse.md new file mode 100644 index 00000000..bcdd8a49 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/4-PQconninfoParse.md @@ -0,0 +1,31 @@ +--- +title: PQconninfoParse +summary: PQconninfoParse +author: Guo Huan +date: 2021-05-17 +--- + +# PQconninfoParse + +## 功能描述 + +根据连接,返回已解析的连接选项。 + +## 原型 + +``` +PQconninfoOption* PQconninfoParse(const char* conninfo, char** errmsg); +``` + +## 参数 + +**表 1** + +| **关键字** | **参数说明** | +| :--------- | :----------------------------------------------------------- | +| conninfo | 被传递的字符串。可以为空,这样将会使用默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。 | +| errmsg | 错误信息。 | + +## 返回值 + +PQconninfoOption类型指针。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/5-PQconnectStart.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/5-PQconnectStart.md new file mode 100644 index 00000000..c8d0f3e1 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/5-PQconnectStart.md @@ -0,0 +1,30 @@ +--- +title: PQconnectStart +summary: PQconnectStart +author: Guo Huan +date: 2021-05-17 +--- + +# PQconnectStart + +## 功能描述 + +与数据库服务器建立一次非阻塞的连接。 + +## 原型 + +``` +PGconn* PQconnectStart(const char* conninfo); +``` + +## 参数 + +**表 1** + +| **关键字** | **参数说明** | +| :--------- | :----------------------------------------------------------- | +| conninfo | 连接信息字符串。可以为空,这样将会使用默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。 | + +## 返回值 + +PGconn类型指针。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/6-PQerrorMessage.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/6-PQerrorMessage.md new file mode 100644 index 00000000..9b6df53e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/6-PQerrorMessage.md @@ -0,0 +1,34 @@ +--- +title: PQerrorMessage +summary: PQerrorMessage +author: Guo Huan +date: 2021-05-17 +--- + +# PQerrorMessage + +## 功能描述 + +返回连接上的错误信息。 + +## 原型 + +``` +char* PQerrorMessage(const PGconn* conn); +``` + +## 参数 + +**表 1** + +| **关键字** | **参数说明** | +| :--------- | :----------- | +| conn | 连接句柄。 | + +## 返回值 + +char类型指针。 + +## 示例 + +请参见[示例](../../libpq-example.md)章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/7-PQsetdbLogin.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/7-PQsetdbLogin.md new file mode 100644 index 00000000..4c9e3eb4 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/7-PQsetdbLogin.md @@ -0,0 +1,51 @@ +--- +title: PQsetdbLogin +summary: PQsetdbLogin +author: Guo Huan +date: 2021-05-17 +--- + +# PQsetdbLogin + +## 功能描述 + +与数据库服务器建立一个新的链接。 + +## 原型 + +``` +PGconn *PQsetdbLogin(const char *pghost, + const char *pgport, + const char *pgoptions, + const char *pgtty, + const char *dbName, + const char *login, + const char *pwd); +``` + +## 参数 + +**表 1** PQsetdbLogin参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------------------------------------------- | +| pghost | 要链接的主机名,详见链接字符章节描述的host字段。 | +| pgport | 主机服务器的端口号,详见链接字符描述的port字段。 | +| pgoptions | 添加命令行选项以在运行时发送到服务器,详见链接字符描述的options字段。 | +| pgtty | 忽略(以前,这个选项声明服务器日志的输出方向) | +| dbName | 要链接的数据库名,详见链接字符描述的dbname字段。 | +| login | 要链接的用户名,详见链接字符章节描述的user字段。 | +| pwd | 如果服务器要求口令认证,所用的口令,详见链接字符描述的password字段。 | + +## 返回值 + +PGconn *:指向包含链接的对象指针,内存在函数内部申请。 + +## 注意事项 + +- 该函数为PQconnectdb前身,参数个数固定,未定义参数被调用时使用缺省值,若需要给固定参数设置缺省值,则可赋值NULL或者空字符串。 +- 若dbName中包含“=”或链接URL的有效前缀,则该dbName被看做一个conninfo字符串并传递至PQconnectdb中,其余参数与PQconnectdbParams保持一致。 + +## 示例 + +请参见[示例](../../libpq-example.md)章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/8-PQfinish.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/8-PQfinish.md new file mode 100644 index 00000000..6e9fa95a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/8-PQfinish.md @@ -0,0 +1,34 @@ +--- +title: PQfinish +summary: PQfinish +author: Guo Huan +date: 2021-05-17 +--- + +# PQfinish + +## 功能描述 + +关闭与服务器的连接,同时释放被PGconn对象使用的存储器。 + +## 原型 + +``` +void PQfinish(PGconn *conn); +``` + +## 参数 + +**表 1** PQfinish参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| conn | 指向包含链接的对象指针。 | + +## 注意事项 + +若PQstatus判断服务器链接尝试失败,应用程序调用PQfinish释放被PGconn对象使用的存储器,PQfinish调用后PGconn指针不可再次使用。 + +## 示例 + +请参见[示例](../../libpq-example.md)章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/9-PQreset.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/9-PQreset.md new file mode 100644 index 00000000..81d730f7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/1-database-connection-control-functions/9-PQreset.md @@ -0,0 +1,34 @@ +--- +title: PQreset +summary: PQreset +author: Guo Huan +date: 2021-05-17 +--- + +# PQreset + +## 功能描述 + +重置与服务器的通讯端口。 + +## 原型 + +``` +void PQreset(PGconn *conn); +``` + +## 参数 + +**表 1** PQreset参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| conn | 指向包含链接的对象指针。 | + +## 注意事项 + +此函数将关闭与服务器的连接并且试图与同一个服务器重建新的连接,并使用所有前面使用过的参数。该函数在链接异常后进行故障恢复时很有用。 + +## 示例 + +请参见[示例](../../libpq-example.md)章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/1-PQclear.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/1-PQclear.md new file mode 100644 index 00000000..899cfea8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/1-PQclear.md @@ -0,0 +1,34 @@ +--- +title: PQclear +summary: PQclear +author: Guo Huan +date: 2021-05-17 +--- + +# PQclear + +## 功能描述 + +释放与PGresult相关联的存储空间,任何不再需要的查询结果都应该用PQclear释放掉。 + +## 原型 + +``` +void PQclear(PGresult *res); +``` + +## 参数 + +**表 1** PQclear参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| res | 包含查询结果的对象指针。 | + +## 注意事项 + +PGresult不会自动释放,当提交新的查询时它并不消失,甚至断开连接后也不会。要删除它,必须调用PQclear,否则则会有内存泄漏。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/10-PQntuples.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/10-PQntuples.md new file mode 100644 index 00000000..4cd91386 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/10-PQntuples.md @@ -0,0 +1,34 @@ +--- +title: PQntuples +summary: PQntuples +author: Guo Huan +date: 2021-05-17 +--- + +# PQntuples + +## 功能描述 + +返回查询结果中的行(元组)数。因为它返回一个整数结果,在 32 位操作系统上大型的结果集可能使返回值溢出。 + +## 原型 + +``` +int PQntuples(const PGresult *res); +``` + +## 参数 + +**表 1** PQntuples参数 + +| **关键字** | **参数说明** | +| :--------- | :------------- | +| res | 操作结果句柄。 | + +## 返回值 + +int类型数字 + +## 示例 + +参见:示例 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/11-PQprepare.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/11-PQprepare.md new file mode 100644 index 00000000..fefdd9f3 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/11-PQprepare.md @@ -0,0 +1,50 @@ +--- +title: PQprepare +summary: PQprepare +author: Guo Huan +date: 2021-05-17 +--- + +# PQprepare + +## 功能描述 + +用给定的参数提交请求,创建一个预备语句,然后等待结束。 + +## 原型 + +``` +PGresult *PQprepare(PGconn *conn, + const char *stmtName, + const char *query, + int nParams, + const Oid *paramTypes); +``` + +## 参数 + +**表 1** PQprepare参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| conn | 指向包含链接的对象指针。 | +| stmtName | 需要执行的*stmt*名称。 | +| query | 需要执行的查询字符串。 | +| nParams | 参数个数。 | +| paramTypes | 声明参数类型的数组。 | + +## 返回值 + +PGresult:包含查询结果的对象指针。 + +## 注意事项 + +- PQprepare创建一个为PQexecPrepared执行用的预备语句,本特性支持命令的重复执行,不需要每次都进行解析和规划。PQprepare仅在协议3.0及以后的连接中支持,使用协议2.0时,PQprepare将失败。 +- 该函数从查询字符串创建一个名为stmtName的预备语句,该查询字符串必须包含一个SQL命令。stmtName可以是”“来创建一个未命名的语句,在这种情况下,任何预先存在的未命名的语句都将被自动替换;否则,如果在当前会话中已经定义了语句名称,则这是一个错误。如果使用了任何参数,那么在查询中将它们称为$1,$2等。nParams是在paramTypes[]数组中预先指定类型的参数的数量。(当nParams为0时,数组指针可以为NULL) paramTypes[]通过OID指定要分配给参数符号的数据类型。如果paramTypes为NULL ,或者数组中的任何特定元素为零,服务器将按照对非类型化字面字符串的相同方式为参数符号分配数据类型。另外,查询可以使用数字高于nParams的参数符号;还将推断这些符号的数据类型。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: +> 通过执行SQLPREPARE语句,还可以创建与PQexecPrepared一起使用的预备语句。此外,虽然没有用于删除预备语句的libpq函数,但是SQL DEALLOCATE语句可用于此目的。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/12-PQresultStatus.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/12-PQresultStatus.md new file mode 100644 index 00000000..8e78886e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/12-PQresultStatus.md @@ -0,0 +1,72 @@ +--- +title: PQresultStatus +summary: PQresultStatus +author: Guo Huan +date: 2021-05-17 +--- + +# PQresultStatus + +## 功能描述 + +返回命令的结果状态。 + +## 原型 + +``` +ExecStatusType PQresultStatus(const PGresult *res); +``` + +## 参数 + +**表 1** PQresultStatus参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| res | 包含查询结果的对象指针。 | + +## 返回值 + +PQresultStatus:命令执行结果的枚举,包括: + +``` +PQresultStatus可以返回下面数值之一: +PGRES_EMPTY_QUERY +发送给服务器的字串是空的。 + +PGRES_COMMAND_OK +成功完成一个不返回数据的命令。 + +PGRES_TUPLES_OK +成功执行一个返回数据的查询(比如SELECT或者SHOW)。 + +PGRES_COPY_OUT +(从服务器)Copy Out (拷贝出)数据传输开始。 + +PGRES_COPY_IN +Copy In(拷贝入)(到服务器)数据传输开始。 + +PGRES_BAD_RESPONSE +服务器的响应无法理解。 + +PGRES_NONFATAL_ERROR +发生了一个非致命错误(通知或者警告)。 + +PGRES_FATAL_ERROR +发生了一个致命错误。 + +PGRES_COPY_BOTH +拷贝入/出(到和从服务器)数据传输开始。这个特性当前只用于流复制, 所以这个状态不会在普通应用中发生。 + +PGRES_SINGLE_TUPLE +PGresult包含一个来自当前命令的结果元组。 这个状态只在查询选择了单行模式时发生 +``` + +## 注意事项 + +- 请注意,恰好检索到零行的SELECT命令仍然显示PGRES_TUPLES_OK。PGRES_COMMAND_OK用于永远不能返回行的命令(插入或更新,不带返回子句等)。PGRES_EMPTY_QUERY响应可能表明客户端软件存在bug。 +- 状态为PGRES_NONFATAL_ERROR的结果永远不会由PQexec或其他查询执行函数直接返回,此类结果将传递给通知处理程序。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/2-PQexec.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/2-PQexec.md new file mode 100644 index 00000000..01bbbdfd --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/2-PQexec.md @@ -0,0 +1,42 @@ +--- +title: PQexec +summary: PQexec +author: Guo Huan +date: 2021-05-17 +--- + +# PQexec + +## 功能描述 + +向服务器提交一条命令并等待结果。 + +## 原型 + +``` +PGresult *PQexec(PGconn *conn, const char *command); +``` + +## 参数 + +**表 1** PQexec参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| conn | 指向包含链接的对象指针。 | +| command | 需要执行的查询字符串。 | + +## 返回值 + +PGresult:包含查询结果的对象指针。 + +## 注意事项 + +应该调用PQresultStatus函数来检查任何错误的返回值(包括空指针的值,在这种情况下它将返回PGRES_FATAL_ERROR)。使用PQerrorMessage获取有关错误的更多信息。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: +> 命令字符串可以包括多个SQL命令(用分号分隔)。在一个PQexec调用中发送的多个查询是在一个事务里处理的,除非在查询字符串里有明确的BEGIN/COMMIT命令把整个字符串分隔成多个事务。请注意,返回的PGresult结构只描述字符串里执行的最后一条命令的结果,如果有一个命令失败,那么字符串处理的过程就会停止,并且返回的PGresult会描述错误条件。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/3-PQexecParams.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/3-PQexecParams.md new file mode 100644 index 00000000..f88c7a59 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/3-PQexecParams.md @@ -0,0 +1,44 @@ +--- +title: PQexecParams +summary: PQexecParams +author: Guo Huan +date: 2021-05-17 +--- + +# PQexecParams + +## 功能描述 + +执行一个绑定参数的命令。 + +## 原型 + +``` +PGresult* PQexecParams(PGconn* conn, + const char* command, + int nParams, + const Oid* paramTypes, + const char* const* paramValues, + const int* paramLengths, + const int* paramFormats, + int resultFormat); +``` + +## 参数 + +**表 1** PQexecParams参数 + +| **关键字** | **参数说明** | +| :----------- | :----------------------------- | +| conn | 连接句柄。 | +| command | SQL文本串。 | +| nParams | 绑定参数的个数 | +| paramTypes | 绑定参数类型。 | +| paramValues | 绑定参数的值。 | +| paramLengths | 参数长度。 | +| paramFormats | 参数格式(文本或二进制)。 | +| resultFormat | 返回结果格式(文本或二进制)。 | + +## 返回值 + +PGresult类型指针。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/4-PQexecParamsBatch.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/4-PQexecParamsBatch.md new file mode 100644 index 00000000..f86d6a2a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/4-PQexecParamsBatch.md @@ -0,0 +1,46 @@ +--- +title: PQexecParamsBatch +summary: PQexecParamsBatch +author: Guo Huan +date: 2021-05-17 +--- + +# PQexecParamsBatch + +## 功能描述 + +执行一个批量绑定参数的命令。 + +## 原型 + +``` +PGresult* PQexecParamsBatch(PGconn* conn, + const char* command, + int nParams, + int nBatch, + const Oid* paramTypes, + const char* const* paramValues, + const int* paramLengths, + const int* paramFormats, + int resultFormat); +``` + +## 参数 + +**表 1** PQexecParamsBatch参数 + +| **关键字** | **参数说明** | +| :----------- | :----------------------------- | +| conn | 连接句柄。 | +| command | SQL文本串。 | +| nParams | 绑定参数的个数。 | +| nBatch | 批量操作数。 | +| paramTypes | 绑定参数类型。 | +| paramValues | 绑定参数的值。 | +| paramLengths | 参数长度。 | +| paramFormats | 参数格式(文本或二进制)。 | +| resultFormat | 返回结果格式(文本或二进制)。 | + +## 返回值 + +PGresult类型指针。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/5-PQexecPrepared.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/5-PQexecPrepared.md new file mode 100644 index 00000000..e524fe03 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/5-PQexecPrepared.md @@ -0,0 +1,42 @@ +--- +title: PQexecPrepared +summary: PQexecPrepared +author: Guo Huan +date: 2021-05-17 +--- + +# PQexecPrepared + +## 功能描述 + +发送一个请求来用给定参数执行一个预备语句,并且等待结果。 + +## 原型 + +``` +PGresult* PQexecPrepared(PGconn* conn, + const char* stmtName, + int nParams, + const char* const* paramValues, + const int* paramLengths, + const int* paramFormats, + int resultFormat); +``` + +## 参数 + +**表 1** PQexecPrepared参数 + +| **关键字** | **参数说明** | +| :----------- | :----------------------------------------------------------- | +| conn | 连接句柄。 | +| stmtName | **stmt**名称,可以用”“或者NULL来引用未命名语句,否则它必须是一个现有预备语句的名字。 | +| nParams | 参数个数。 | +| paramValues | 参数的实际值。 | +| paramLengths | 参数的实际数据长度。 | +| paramFormats | 参数的格式(文本或二进制)。 | +| resultFormat | 结果的格式(文本或二进制)。 | + +## 返回值 + +PGresult类型指针。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/6-PQexecPreparedBatch.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/6-PQexecPreparedBatch.md new file mode 100644 index 00000000..83bb4e73 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/6-PQexecPreparedBatch.md @@ -0,0 +1,44 @@ +--- +title: PQexecPreparedBatch +summary: PQexecPreparedBatch +author: Guo Huan +date: 2021-05-17 +--- + +# PQexecPreparedBatch + +## 功能描述 + +发送一个请求来用给定的批量参数执行一个预备语句,并且等待结果。 + +## 原型 + +``` +PGresult* PQexecPreparedBatch(PGconn* conn, + const char* stmtName, + int nParams, + int nBatchCount, + const char* const* paramValues, + const int* paramLengths, + const int* paramFormats, + int resultFormat); +``` + +## 参数 + +**表 1** PQexecPreparedBatch参数 + +| **关键字** | **参数说明** | +| :----------- | :----------------------------------------------------------- | +| conn | 连接句柄。 | +| stmtName | **stmt**名称,可以用”“或者NULL来引用未命名语句,否则它必须是一个现有预备语句的名字。 | +| nParams | 参数个数。 | +| nBatchCount | 批量数。 | +| paramValues | 参数的实际值。 | +| paramLengths | 参数的实际数据长度。 | +| paramFormats | 参数的格式(文本或二进制)。 | +| resultFormat | 结果的格式(文本或二进制)。 | + +## 返回值 + +PGresult类型指针。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/7-PQfname.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/7-PQfname.md new file mode 100644 index 00000000..3f955679 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/7-PQfname.md @@ -0,0 +1,36 @@ +--- +title: PQfname +summary: PQfname +author: Guo Huan +date: 2021-05-17 +--- + +# PQfname + +## 功能描述 + +返回与给定列号相关联的列名。列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给PQclear之后被释放。 + +## 原型 + +``` +char *PQfname(const PGresult *res, + int column_number); +``` + +## 参数 + +**表 1** PQfname参数 + +| **关键字** | **参数说明** | +| :------------ | :------------- | +| res | 操作结果句柄。 | +| column_number | 列数。 | + +## 返回值 + +char类型指针。 + +## 示例 + +参见:示例 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/8-PQgetvalue.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/8-PQgetvalue.md new file mode 100644 index 00000000..5227b088 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/8-PQgetvalue.md @@ -0,0 +1,42 @@ +--- +title: PQgetvalue +summary: PQgetvalue +author: Guo Huan +date: 2021-05-17 +--- + +# PQgetvalue + +## 功能描述 + +返回一个PGresult的一行的单一域值。行和列号从 0 开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给PQclear之后被释放。 + +## 原型 + +``` +char *PQgetvalue(const PGresult *res, + int row_number, + int column_number); +``` + +## 参数 + +**表 1** PQgetvalue参数 + +| **关键字** | **参数说明** | +| :------------ | :------------- | +| res | 操作结果句柄。 | +| row_number | 行数。 | +| column_number | 列数。 | + +## 返回值 + +对于文本格式的数据,PQgetvalue返回的值是该域值的一种空值结束的字符串表示。 + +对于二进制格式的数据,该值是由该数据类型的typsend和typreceive函数决定的二进制表示。 + +如果该域值为空,则返回一个空串。 + +## 示例 + +参见:示例 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/9-PQnfields.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/9-PQnfields.md new file mode 100644 index 00000000..618fb7d9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/2-database-statement-execution-functions/9-PQnfields.md @@ -0,0 +1,34 @@ +--- +title: PQnfields +summary: PQnfields +author: Guo Huan +date: 2021-05-17 +--- + +# PQnfields + +## 功能描述 + +返回查询结果中每一行的列(域)数。 + +## 原型 + +``` +int PQnfields(const PGresult *res); +``` + +## 参数 + +**表 1** PQnfields参数 + +| **关键字** | **参数说明** | +| :--------- | :------------- | +| res | 操作结果句柄。 | + +## 返回值 + +int类型数字。 + +## 示例 + +参见:示例 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/1-functions-for-asynchronous-command-processing-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/1-functions-for-asynchronous-command-processing-overview.md new file mode 100644 index 00000000..f782a8b1 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/1-functions-for-asynchronous-command-processing-overview.md @@ -0,0 +1,17 @@ +--- +title: 说明 +summary: 说明 +author: Guo Huan +date: 2021-05-17 +--- + +# 说明 + +PQexec函数对普通的同步应用里提交命令已经足够使用。但是它却有几个缺陷,而这些缺陷可能对某些用户很重要: + +- PQexec等待命令结束,而应用可能还有其它的工作要做(比如维护用户界面等),此时PQexec可不想阻塞在这里等待响应。 +- 因为客户端应用在等待结果的时候是处于挂起状态的,所以应用很难判断它是否该尝试结束正在进行的命令。 +- PQexec只能返回一个PGresult结构。如果提交的命令字符串包含多个SQL命令,除了最后一个PGresult以外都会被PQexec丢弃。 +- PQexec总是收集命令的整个结果,将其缓存在一个PGresult中。虽然这为应用简化了错误处理逻辑,但是对于包含多行的结果是不切实际的。 + +不想受到这些限制的应用可以改用下面的函数,这些函数也是构造PQexec的函数:PQsendQuery和PQgetResult。PQsendQueryParams,PQsendPrepare,PQsendQueryPrepared也可以和PQgetResult一起使用。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/2-PQsendQuery.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/2-PQsendQuery.md new file mode 100644 index 00000000..b8c3257d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/2-PQsendQuery.md @@ -0,0 +1,39 @@ +--- +title: PQsendQuery +summary: PQsendQuery +author: Guo Huan +date: 2021-05-17 +--- + +# PQsendQuery + +## 功能描述 + +向服务器提交一个命令而不等待结果。如果查询成功发送则返回1,否则返回0。 + +## 原型 + +```c +int PQsendQuery(PGconn *conn, const char *command); +``` + +## 参数 + +**表 1** PQsendQuery参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| conn | 指向包含链接的对象指针。 | +| command | 需要执行的查询字符串. | + +## 返回值 + +int:执行结果为1表示成功,0表示失败,失败原因存到conn->errorMessage中。 + +## 注意事项 + +在成功调用PQsendQuery后,调用PQgetResult一次或者多次获取结果。PQgetResult返回空指针表示命令已执行完成,否则不能再次调用PQsendQuery(在同一连接上)。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/3-PQsendQueryParams.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/3-PQsendQueryParams.md new file mode 100644 index 00000000..9c5d4587 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/3-PQsendQueryParams.md @@ -0,0 +1,52 @@ +--- +title: PQsendQueryParams +summary: PQsendQueryParams +author: Guo Huan +date: 2021-05-17 +--- + +# PQsendQueryParams + +## 功能描述 + +给服务器提交一个命令和分隔的参数,而不等待结果。 + +## 原型 + +```c +int PQsendQueryParams(PGconn *conn, + const char *command, + int nParams, + const Oid *paramTypes, + const char * const *paramValues, + const int *paramLengths, + const int *paramFormats, + int resultFormat); +``` + +## 参数 + +**表 1** PQsendQueryParams参数 + +| **关键字** | **参数说明** | +| :----------- | :----------------------- | +| conn | 指向包含链接的对象指针。 | +| command | 需要执行的查询字符串。 | +| nParams | 参数个数。 | +| paramTypes | 参数类型。 | +| paramValues | 参数值。 | +| paramLengths | 参数长度。 | +| paramFormats | 参数格式。 | +| resultFormat | 结果的格式。 | + +## 返回值 + +int:执行结果为1表示成功,0表示失败,失败原因存到conn->errorMessage中。 + +## 注意事项 + +该函数等效于PQsendQuery,只是查询参数可以和查询字符串分开声明。函数的参数处理和PQexecParams一样,和PQexecParams类似,它不能在2.0版本的协议连接上工作,并且它只允许在查询字符串里出现一条命令。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/4-PQsendPrepare.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/4-PQsendPrepare.md new file mode 100644 index 00000000..cfd6aea6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/4-PQsendPrepare.md @@ -0,0 +1,46 @@ +--- +title: PQsendPrepare +summary: PQsendPrepare +author: Guo Huan +date: 2021-05-17 +--- + +# PQsendPrepare + +## 功能描述 + +发送一个请求,创建一个给定参数的预备语句,而不等待结束。 + +## 原型 + +```c +int PQsendPrepare(PGconn *conn, + const char *stmtName, + const char *query, + int nParams, + const Oid *paramTypes); +``` + +## 参数 + +**表 1** PQsendPrepare参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------- | +| conn | 指向包含链接的对象指针。 | +| stmtName | 需要执行的*stmt*名称。 | +| query | 需要执行的查询字符串。 | +| nParams | 参数个数。 | +| paramTypes | 声明参数类型的数组。 | + +## 返回值 + +int:执行结果为1表示成功,0表示失败,失败原因存到conn->errorMessage中。 + +## 注意事项 + +该函数为PQprepare的异步版本:如果能够分派请求,则返回1,否则返回0。调用成功后,调用PQgetResult判断服务端是否成功创建了preparedStatement。函数的参数与PQprepare一样处理。与PQprepare一样,它也不能在2.0协议的连接上工作。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/5-PQsendQueryPrepared.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/5-PQsendQueryPrepared.md new file mode 100644 index 00000000..43f6f09e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/5-PQsendQueryPrepared.md @@ -0,0 +1,50 @@ +--- +title: PQsendQueryPrepared +summary: PQsendQueryPrepared +author: Guo Huan +date: 2021-05-17 +--- + +# PQsendQueryPrepared + +## 功能描述 + +发送一个请求执行带有给出参数的预备语句,不等待结果。 + +## 原型 + +```c +int PQsendQueryPrepared(PGconn *conn, + const char *stmtName, + int nParams, + const char * const *paramValues, + const int *paramLengths, + const int *paramFormats, + int resultFormat); +``` + +## 参数 + +**表 1** PQsendQueryPrepared参数 + +| **关键字** | **参数说明** | +| :----------- | :--------------------------- | +| conn | 指向包含链接信息的对象指针。 | +| stmtName | 需要执行的stmt名称。 | +| nParams | 参数个数。 | +| paramValues | 参数值。 | +| paramLengths | 参数长度。 | +| paramFormats | 参数格式。 | +| resultFormat | 结果的格式。 | + +## 返回值 + +int:执行结果为1表示成功,0表示失败,失败原因存到conn->error_message中。 + +## 注意事项 + +该函数类似于PQsendQueryParams,但是要执行的命令是通过命名一个预先准备的语句来指定的,而不是提供一个查询字符串。该函数的参数与PQexecPrepared一样处理。和PQexecPrepared一样,它也不能在2.0协议的连接上工作。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/6-PQflush.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/6-PQflush.md new file mode 100644 index 00000000..6af91b8d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/3-functions-for-asynchronous-command-processing/6-PQflush.md @@ -0,0 +1,38 @@ +--- +title: PQflush +summary: PQflush +author: Guo Huan +date: 2021-05-17 +--- + +# PQflush + +## 功能描述 + +尝试将任何排队的输出数据刷新到服务器。 + +## 原型 + +```c +int PQflush(PGconn *conn); +``` + +## 参数 + +**表 1** PQflush参数 + +| **关键字** | **参数说明** | +| :--------- | :------------------------- | +| conn | 指向包含链接信息的对象指针 | + +## 返回值 + +int:如果成功(或者如果发送队列为空),则返回0;如果由于某种原因失败,则返回-1;如果发送队列中的所有数据都发送失败,则返回1。(此情况只有在连接为非阻塞时才能发生),失败原因存到conn->error_message中。 + +## 注意事项 + +在非阻塞连接上发送任何命令或数据之后,调用PQflush。如果返回1,则等待套接字变为读或写就绪。如果为写就绪状态,则再次调用PQflush。如果已经读到,调用PQconsumeInput,然后再次调用PQflush。重复,直到PQflush返回0。(必须检查读就绪,并用PQconsumeInput排出输入,因为服务器可以阻止试图向我们发送数据,例如。通知信息,直到我们读完它才会读我们的数据。)一旦PQflush返回0,就等待套接字准备好,然后按照上面描述读取响应。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/1-PQgetCancel.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/1-PQgetCancel.md new file mode 100644 index 00000000..245cff30 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/1-PQgetCancel.md @@ -0,0 +1,38 @@ +--- +title: PQgetCancel +summary: PQgetCancel +author: Guo Huan +date: 2021-05-17 +--- + +# PQgetCancel + +## 功能描述 + +创建一个数据结构,其中包含取消通过特定数据库连接发出的命令所需的信息。 + +## 原型 + +```c +PGcancel *PQgetCancel(PGconn *conn); +``` + +## 参数 + +**表 1** PQgetCancel参数 + +| **关键字** | **参数说明** | +| :--------- | :--------------------------- | +| conn | 指向包含链接信息的对象指针。 | + +## 返回值 + +PGcancel:指向包含cancel信息对象的指针。 + +## 注意事项 + +PQgetCancel创建一个给定PGconn连接对象的PGcancel对象。如果给定的conn是NULL或无效连接,它将返回NULL。PGcancel对象是一个不透明的结构,应用程序不能直接访问它;它只能传递给PQcancel或PQfreeCancel。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/2-PQfreeCancel.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/2-PQfreeCancel.md new file mode 100644 index 00000000..8627766c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/2-PQfreeCancel.md @@ -0,0 +1,34 @@ +--- +title: PQfreeCancel +summary: PQfreeCancel +author: Guo Huan +date: 2021-05-17 +--- + +# PQfreeCancel + +## 功能描述 + +释放PQgetCancel创建的数据结构。 + +## 原型 + +```c +void PQfreeCancel(PGcancel *cancel); +``` + +## 参数 + +**表 1** PQfreeCancel参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------------- | +| cancel | 指向包含cancel信息的对象指针。 | + +## 注意事项 + +PQfreeCancel释放一个由前面的PQgetCancel创建的数据对象。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/3-PQcancel.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/3-PQcancel.md new file mode 100644 index 00000000..c7e198ff --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/2-libpq/4-functions-for-canceling-queries-in-progress/3-PQcancel.md @@ -0,0 +1,41 @@ +--- +title: PQcancel +summary: PQcancel +author: Guo Huan +date: 2021-05-17 +--- + +# PQcancel + +## 功能描述 + +要求服务器放弃处理当前命令。 + +## 原型 + +```c +int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); +``` + +## 参数 + +**表 1** PQcancel参数 + +| **关键字** | **参数说明** | +| :--------- | :----------------------------- | +| cancel | 指向包含cancel信息的对象指针。 | +| errbuf | 出错保存错误信息的buffer。 | +| errbufsize | 保存错误信息的buffer大小。 | + +## 返回值 + +int:执行结果为1表示成功,0表示失败,失败原因存到errbuf中。 + +## 注意事项 + +- 成功发送并不保证请求将产生任何效果。如果取消有效,当前命令将提前终止并返回错误结果。如果取消失败(例如,因为服务器已经处理完命令),无返回结果。 +- 如果errbuf是信号处理程序中的局部变量,则可以安全地从信号处理程序中调用PQcancel。就PQcancel而言,PGcancel对象是只读的,因此它也可以从一个线程中调用,这个线程与操作PGconn对象线程是分离的。 + +## 示例 + +请参见示例章节。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/dependent-header-files-of-libpq.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/dependent-header-files-of-libpq.md new file mode 100644 index 00000000..2da4447a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/dependent-header-files-of-libpq.md @@ -0,0 +1,10 @@ +--- +title: libpq使用依赖的头文件 +summary: libpq使用依赖的头文件 +author: Guo Huan +date: 2022-04-26 +--- + +# libpq使用依赖的头文件 + +使用libpq的前端程序必须包括头文件libpq-fe.h并且必须与libpq库链接。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/development-process.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/development-process.md new file mode 100644 index 00000000..6add699e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/development-process.md @@ -0,0 +1,34 @@ +--- +title: 开发流程 +summary: 开发流程 +author: Guo Huan +date: 2022-04-26 +--- + +# 开发流程 + +编译并且链接一个libpq的源程序,需要做下面的一些事情: + +1. 解压相应的发布包(如`MogDB-3.0.1-CentOS-64bit-Libpq.tar.gz`)文件,其中include文件夹下的头文件为所需的头文件,lib文件夹中为所需的libpq库文件。 + + > **说明**: 除libpq-fe.h外,include文件夹下默认还存在头文件postgres_ext.h,gs_thread.h,gs_threadlocal.h,这三个头文件是libpq-fe.h的依赖文件。 + +2. 包含libpq-fe.h头文件: + + ``` + #include + ``` + +3. 通过-I directory选项,提供头文件的安装位置(有些时候编译器会查找缺省的目录,因此可以忽略这些选项)。如: + + ``` + gcc -I (头文件所在目录) -L (libpq库所在目录) testprog.c -lpq + ``` + +4. 如果要使用制作文件(makefile),向CPPFLAGS、LDFLAGS、LIBS变量中增加如下选项: + + ``` + CPPFLAGS += -I (头文件所在目录) + LDFLAGS += -L (libpq库所在目录) + LIBS += -lpq + ``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/libpq-example.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/libpq-example.md new file mode 100644 index 00000000..a55bd0fd --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/libpq-example.md @@ -0,0 +1,280 @@ +--- +title: 示例 +summary: 示例 +author: Guo Huan +date: 2022-04-26 +--- + +# 示例 + +## 常用功能示例代码 + +示例1: + +```c +/* + * testlibpq.c + */ +#include +#include +#include + +static void +exit_nicely(PGconn *conn) +{ + PQfinish(conn); + exit(1); +} + +int +main(int argc, char **argv) +{ + const char *conninfo; + PGconn *conn; + PGresult *res; + int nFields; + int i,j; + + /* + * 用户在命令行上提供了conninfo字符串的值时使用该值 + * 否则环境变量或者所有其它连接参数 + * 都使用缺省值。 + */ + if (argc > 1) + conninfo = argv[1]; + else + conninfo = "dbname=postgres port=42121 host='10.44.133.171' application_name=test connect_timeout=5 sslmode=allow user='test' password='test_1234'"; + + /* 连接数据库 */ + conn = PQconnectdb(conninfo); + + /* 检查后端连接成功建立 */ + if (PQstatus(conn) != CONNECTION_OK) + { + fprintf(stderr, "Connection to database failed: %s", + PQerrorMessage(conn)); + exit_nicely(conn); + } + + /* + * 测试实例涉及游标的使用时候必须使用事务块 + *把全部放在一个 "select * from pg_database" + * PQexec() 里,过于简单,不推荐使用 + */ + + /* 开始一个事务块 */ + res = PQexec(conn, "BEGIN"); + if (PQresultStatus(res) != PGRES_COMMAND_OK) + { + fprintf(stderr, "BEGIN command failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + + /* + * 在结果不需要的时候PQclear PGresult,以避免内存泄漏 + */ + PQclear(res); + + /* + * 从系统表 pg_database(数据库的系统目录)里抓取数据 + */ + res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); + if (PQresultStatus(res) != PGRES_COMMAND_OK) + { + fprintf(stderr, "DECLARE CURSOR failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + PQclear(res); + + res = PQexec(conn, "FETCH ALL in myportal"); + if (PQresultStatus(res) != PGRES_TUPLES_OK) + { + fprintf(stderr, "FETCH ALL failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + + /* 打印属性名称 */ + nFields = PQnfields(res); + for (i = 0; i < nFields; i++) + printf("%-15s", PQfname(res, i)); + printf("\n\n"); + + /* 打印行 */ + for (i = 0; i < PQntuples(res); i++) + { + for (j = 0; j < nFields; j++) + printf("%-15s", PQgetvalue(res, i, j)); + printf("\n"); + } + + PQclear(res); + + /* 关闭入口 ... 不用检查错误 ... */ + res = PQexec(conn, "CLOSE myportal"); + PQclear(res); + + /* 结束事务 */ + res = PQexec(conn, "END"); + PQclear(res); + + /* 关闭数据库连接并清理 */ + PQfinish(conn); + + return 0; +} +``` + +示例2: + +```c +/* + * testlibpq2.c + * 测试外联参数和二进制I/O。 + * + * 在运行这个例子之前,用下面的命令填充一个数据库 + * + * + * CREATE TABLE test1 (i int4, t text); + * + * INSERT INTO test1 values (2, 'ho there'); + * + * 期望的输出如下 + * + * + * tuple 0: got + * i = (4 bytes) 2 + * t = (8 bytes) 'ho there' + * + */ +#include +#include +#include +#include +#include + +/* for ntohl/htonl */ +#include +#include + +static void +exit_nicely(PGconn *conn) +{ + PQfinish(conn); + exit(1); +} + +/* + * 这个函数打印查询结果,这些结果是二进制格式,从上面的 + * 注释里面创建的表中抓取出来的 + */ +static void +show_binary_results(PGresult *res) +{ + int i; + int i_fnum, + t_fnum; + + /* 使用 PQfnumber 来避免对结果中的字段顺序进行假设 */ + i_fnum = PQfnumber(res, "i"); + t_fnum = PQfnumber(res, "t"); + + for (i = 0; i < PQntuples(res); i++) + { + char *iptr; + char *tptr; + int ival; + + /* 获取字段值(忽略可能为空的可能) */ + iptr = PQgetvalue(res, i, i_fnum); + tptr = PQgetvalue(res, i, t_fnum); + + /* + * INT4 的二进制表现形式是网络字节序 + * 建议转换成本地字节序 + */ + ival = ntohl(*((uint32_t *) iptr)); + + /* + * TEXT 的二进制表现形式是文本,因此libpq能够给它附加一个字节零 + * 把它看做 C 字符串 + * + */ + + printf("tuple %d: got\n", i); + printf(" i = (%d bytes) %d\n", + PQgetlength(res, i, i_fnum), ival); + printf(" t = (%d bytes) '%s'\n", + PQgetlength(res, i, t_fnum), tptr); + printf("\n\n"); + } +} + +int +main(int argc, char **argv) +{ + const char *conninfo; + PGconn *conn; + PGresult *res; + const char *paramValues[1]; + int paramLengths[1]; + int paramFormats[1]; + uint32_t binaryIntVal; + + /* + * 如果用户在命令行上提供了参数, + * 那么使用该值为conninfo 字符串;否则 + * 使用环境变量或者缺省值。 + */ + if (argc > 1) + conninfo = argv[1]; + else + conninfo = "dbname=postgres port=42121 host='10.44.133.171' application_name=test connect_timeout=5 sslmode=allow user='test' password='test_1234'"; + + /* 和数据库建立连接 */ + conn = PQconnectdb(conninfo); + + /* 检查与服务器的连接是否成功建立 */ + if (PQstatus(conn) != CONNECTION_OK) + { + fprintf(stderr, "Connection to database failed: %s", + PQerrorMessage(conn)); + exit_nicely(conn); + } + + /* 把整数值 "2" 转换成网络字节序 */ + binaryIntVal = htonl((uint32_t) 2); + + /* 为 PQexecParams 设置参数数组 */ + paramValues[0] = (char *) &binaryIntVal; + paramLengths[0] = sizeof(binaryIntVal); + paramFormats[0] = 1; /* 二进制 */ + + res = PQexecParams(conn, + "SELECT * FROM test1 WHERE i = $1::int4", + 1, /* 一个参数 */ + NULL, /* 让后端推导参数类型 */ + paramValues, + paramLengths, + paramFormats, + 1); /* 要求二进制结果 */ + + if (PQresultStatus(res) != PGRES_TUPLES_OK) + { + fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + + show_binary_results(res); + + PQclear(res); + + /* 关闭与数据库的连接并清理 */ + PQfinish(conn); + + return 0; +} +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/link-parameters.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/link-parameters.md new file mode 100644 index 00000000..8f6e8e5c --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4-development-based-on-libpq/link-parameters.md @@ -0,0 +1,52 @@ +--- +title: 链接参数 +summary: 链接参数 +author: Guo Huan +date: 2022-04-26 +--- + +# 链接参数 + +**表 1** 链接参数 + +| 参数 | 描述 | +| :------------------------ | :----------------------------------------------------------- | +| host | 要链接的主机名。如果主机名以斜杠开头,则它声明使用Unix域套接字通讯而不是TCP/IP通讯;该值就是套接字文件所存储的目录。如果没有声明host,那么默认是与位于/tmp目录(或者安装数据库的时候声明的套接字目录)里面的Unix-域套接字链接。在没有Unix域套接字的机器上,默认与localhost链接。
接受以‘,’分割的字符串来指定多个主机名,支持指定多个主机名。 | +| hostaddr | 与之链接的主机的IP地址,是标准的IPv4地址格式,比如,172.28.40.9。如果机器支持IPv6,那么也可以使用IPv6的地址。如果声明了一个非空的字符串,那么使用TCP/IP通讯机制。
接受以‘,’分割的字符串来指定多个IP地址,支持指定多个IP地址。
使用hostaddr取代host可以让应用避免一次主机名查找,这一点对于那些有时间约束的应用来说可能是非常重要的。不过,GSSAPI或SSPI认证方法要求主机名(host)。因此,应用下面的规则:
1. 如果声明了不带hostaddr的host那么就强制进行主机名查找。
2. 如果声明中没有host,hostaddr的值给出服务器网络地址;如果认证方法要求主机名,那么链接尝试将失败。
3. 如果同时声明了host和hostaddr,那么hostaddr的值作为服务器网络地址。host的值将被忽略,除非认证方法需要它,在这种情况下它将被用作主机名。
须知:
- 要注意如果host不是网络地址hostaddr处的服务器名,那么认证很有可能失败。
- 如果主机名(host)和主机地址都没有,那么libpq将使用一个本地的Unix域套接字进行链接;或者是在没有Unix域套接字的机器上,它将尝试与localhost链接。 | +| port | 主机服务器的端口号,或者在Unix域套接字链接时的套接字扩展文件名。
接受以‘,’分割的字符串来指定多个端口号,支持指定多个端口号。 | +| user | 要链接的用户名,缺省是与运行该应用的用户操作系统名同名的用户。 | +| dbname | 数据库名,缺省和用户名相同。 | +| password | 如果服务器要求口令认证,所用的口令。 | +| connect_timeout | 链接的最大等待时间,以秒计(用十进制整数字符串书写),0或者不声明表示无穷。不建议把链接超时的值设置得小于2秒。 | +| client_encoding | 为这个链接设置client_encoding配置参数。除了对应的服务器选项接受的值,你可以使用auto从客户端中的当前环境中确定正确的编码(Unix系统上是LC_CTYPE环境变量)。 | +| tty | 忽略(以前,该参数指定了发送服务器调试输出的位置)。 | +| options | 添加命令行选项以在运行时发送到服务器。 | +| application_name | 为application_name配置参数指定一个值,表明当前用户身份。 | +| fallback_application_name | 为[application_name](http://www.postgres.cn/docs/12/runtime-config-logging.html#GUC-APPLICATION-NAME)配置参数指定一个后补值。如果通过一个连接参数或PGAPPNAME环境变量没有为application_name给定一个值,将使用这个值。在希望设置一个默认应用名但不希望它被用户覆盖的一般工具程序中指定一个后补值很有用。 | +| keepalives | 控制客户端侧的TCP保持激活是否使用。缺省值是1,意思为打开,但是如果不想要保持激活,你可以更改为0,意思为关闭。通过Unix域套接字做的链接忽略这个参数。 | +| keepalives_idle | 在TCP应该发送一个保持激活的信息给服务器之后,控制不活动的秒数。0值表示使用系统缺省。通过Unix域套接字做的链接或者如果禁用了保持激活则忽略这个参数。 | +| keepalives_interval | 在TCP保持激活信息没有被应该传播的服务器承认之后,控制秒数。0值表示使用系统缺省。通过Unix域套接字做的链接或者如果禁用了保持激活则忽略这个参数。 | +| keepalives_count | 添加命令行选项以在运行时发送到服务器。例如,设置为-c comm_debug_mode=off设置guc参数comm_debug_mode参数的会话的值为off。 | +| rw_timeout | 设置客户端连接读写超时时间。 | +| sslmode | 启用SSL加密的方式:
- disable:不使用SSL安全连接。
- allow:如果数据库服务器要求使用,则可以使用SSL安全加密连接,但不验证数据库服务器的真实性。
- prefer:如果数据库支持,那么首选使用SSL安全加密连接,但不验证数据库服务器的真实性。
- require:必须使用SSL安全连接,但是只做了数据加密,而并不验证数据库服务器的真实性。
- verify-ca:必须使用SSL安全连接,当前windows odbc不支持cert方式认证。
- verify-full:必须使用SSL安全连接,当前windows odbc不支持cert方式认证。 | +| sslcompression | 如果设置为1(默认),SSL连接之上传送的数据将被压缩(这要求OpenSSL版本为0.9.8或更高)。如果设置为0,压缩将被禁用(这要求OpenSSL版本为1.0.0或更高)。如果建立的是一个没有SSL的连接,这个参数会被忽略。如果使用的OpenSSL版本不支持该参数,它也会被忽略。压缩会占用CUP时间,但是当瓶颈为网络时可以提高吞吐量。如果CPU性能是限制因素,禁用压缩能够改进响应时间和吞吐量。 | +| sslcert | 这个参数指定客户端SSL证书的文件名,它替换默认的~/.postgresql/postgresql.crt。如果没有建立SSL连接,这个参数会被忽略。 | +| sslkey | 这个参数指定用于客户端证书的密钥位置。它能指定一个会被用来替代默认的~/.postgresql/postgresql.key的文件名,或者它能够指定一个从外部“引擎”(引擎是OpenSSL的可载入模块)得到的密钥。一个外部引擎说明应该由一个冒号分隔的引擎名称以及一个引擎相关的关键标识符组成。如果没有建立SSL连接,这个参数会被忽略。 | +| sslrootcert | 这个参数指定一个包含SSL证书机构(CA)证书的文件名称。如果该文件存在,服务器的证书将被验证是由这些机构之一签发。默认值是~/.postgresql/root.crt。 | +| sslcrl | 这个参数指定SSL证书撤销列表(CRL)的文件名。列在这个文件中的证书如果存在,在尝试认证该服务器证书时会被拒绝。默认值是~/.postgresql/root.crl。 | +| requirepeer | 这个参数指定服务器的操作系统用户,例如requirepeer=postgres。当建立一个Unix域套接字连接时,如果设置了这个参数,客户端在连接开始时检查服务器进程是否运行在指定的用户名之下。如果发现不是,该连接会被一个错误中断。这个参数能被用来提供与TCP/IP连接上SSL证书相似的服务器认证(注意,如果Unix域套接字在/tmp或另一个公共可写的位置,任何用户能启动一个在那里侦听的服务器。使用这个参数来保证你连接的是一个由可信用户运行的服务器)。这个选项只在实现了peer认证方法的平台上受支持。 | +| krbsrvname | 当用GSSAPI认证时,要使用的Kerberos服务名。为了让Kerberos认证成功,这必须匹配在服务器配置中指定的服务名。 | +| gsslib | 用于GSSAPI认证的GSS库。只用在Windows上。设置为gssapi可强制libpq用GSSAPI库来代替默认的SSPI进行认证。 | +| service | 用于附加参数的服务名。它指定保持附加连接参数的pg_service.conf中的一个服务名。这允许应用只指定一个服务名,这样连接参数能被集中维护。 | +| authtype | 不再使用“authtype”,因此将其标记为“不显示”。我们将其保留在数组中,以免拒绝旧应用程序中的conninfo字符串,这些应用程序可能仍在尝试设置它。 | +| remote_nodename | 指定连接本地节点的远端节点名称。 | +| localhost | 指定在一个连接通道中的本地地址。 | +| localport | 指定在一个连接通道中的本地端口。 | +| fencedUdfRPCMode | 控制fenced UDF RPC协议是使用unix域套接字或特殊套接字文件名。缺省值是0,意思为关闭,使用unix domain socket模式,文件类型为“.s.PGSQL.%d”,但是要使用fenced udf ,文件类型为.s.fencedMaster_unixdomain,可以更改为1,意思为开启。 | +| replication | 这个选项决定是否该连接应该使用复制协议而不是普通协议。这是PostgreSQL的复制连接以及pg_basebackup之类的工具在内部使用的协议,但也可以被第三方应用使用。支持下列值,大小写无关:
- true、on、yes、1:连接进入到物理复制模式。
- database:连接进入到逻辑复制模式,连接到dbname参数中指定的数据库。
- false、off、no、0:该连接是一个常规连接,这是默认行为。在物理或者逻辑复制模式中,仅能使用简单查询协议。 | +| backend_version | 传递到远端的后端版本号。 | +| prototype | 设置当前协议级别,默认:PROTO_TCP。 | +| enable_ce | 控制是否允许客户端连接全密态数据库。默认0,如果需要开启,则修改为1。 | +| connection_info | Connection_info是一个包含driver_name、driver_version、driver_path和os_user的json字符串。
如果不为NULL,使用connection_info忽略connectionExtraInf
如果为NULL,生成与libpq相关的连接信息字符串,当connectionExtraInf为false时connection_info只有driver_name和driver_version。 | +| connectionExtraInf | 设置connection_info是否存在扩展信息,默认值为0,如果包含其他信息,则需要设置为1。 | +| target_session_attrs | 设定连接的主机的类型。主机的类型和设定的值一致时才能连接成功。target_session_attrs的设置规则如下:
- any(默认值):可以对所有类型的主机进行连接。
- read-write:当连接的主机允许可读可写时,才进行连接。
- read-only:仅对可读的主机进行连接。
- primary:仅对主备系统中的主机能进行连接。
- standby: 仅对主备系统中的备机进行连接。
- prefer-standby:首先尝试找到一个备机进行连接。如果对hosts列表的所有机器都连接失败,那么尝试“any”模式进行连接。 | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/1-psycopg-based-development.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/1-psycopg-based-development.md new file mode 100644 index 00000000..560bb616 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/1-psycopg-based-development.md @@ -0,0 +1,19 @@ +--- +title: 基于Psycopg开发 +summary: 基于Psycopg开发 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 基于Psycopg开发 + +Psycopg是一种用于执行SQL语句的PythonAPI,可以为PostgreSQL、MogDB数据库提供统一访问接口,应用程序可基于它进行数据操作。Psycopg2是对libpq的封装,主要使用C语言实现,既高效又安全。它具有客户端游标和服务器端游标、异步通信和通知、支持“COPY TO/COPY FROM”功能。支持多种类型Python开箱即用,适配PostgreSQL数据类型;通过灵活的对象适配系统,可以扩展和定制适配。Psycopg2兼容Unicode和Python 3。 + +MogDB数据库提供了对Psycopg2特性的支持,并且支持psycopg2通过SSL模式链接。 + +**表 1** Psycopg支持平台 + +| 操作系统 | 平台 | +| :---------- | :------- | +| EulerOS 2.5 | x86_64位 | +| EulerOS 2.8 | ARM64位 | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md new file mode 100644 index 00000000..b7f2d089 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md @@ -0,0 +1,61 @@ +--- +title: 常用操作 +summary: 常用操作 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 示例:常用操作 + +```bash +import psycopg2 + +#创建连接对象 +conn=psycopg2.connect(database="postgres",user="user",password="password",host="localhost",port=port) +cur=conn.cursor() #创建指针对象 + +#创建连接对象(SSl连接) +conn = psycopg2.connect(dbname="postgres", user="user", password="password", host="localhost", port=port, + sslmode="verify-ca", sslcert="client.crt",sslkey="client.key",sslrootcert="cacert.pem") +注意: 如果sslcert, sslkey,sslrootcert没有填写,默认取当前用户.postgresql目录下对应的client.crt, + client.key, root.crt + +# 创建表 +cur.execute("CREATE TABLE student(id integer,name varchar,sex varchar);") + +#插入数据 +cur.execute("INSERT INTO student(id,name,sex) VALUES(%s,%s,%s)",(1,'Aspirin','M')) +cur.execute("INSERT INTO student(id,name,sex) VALUES(%s,%s,%s)",(2,'Taxol','F')) +cur.execute("INSERT INTO student(id,name,sex) VALUES(%s,%s,%s)",(3,'Dixheral','M')) + +# 获取结果 +cur.execute('SELECT * FROM student') +results=cur.fetchall() +print (results) + +# 关闭连接 +conn.commit() +cur.close() +conn.close() + +psycopg2常用链接方式 +1. conn = psycopg2.connect(dbname="postgres", user="user", password="password", host="localhost", port=port) +2. conn = psycopg2.connect("dbname=postgres user=user password=password host=localhost port=port") +3. 使用日志 +import logging +import psycopg2 +from psycopg2.extras import LoggingConnection + +logging.basicConfig(level=logging.DEBUG) # 日志级别 +logger = logging.getLogger(__name__) + +db_settings = { + "user": "user", + "password": "password", + "host": "localhost", + "database": "postgres", + "port": port +} +conn = psycopg2.connect(connection_factory=LoggingConnection, **db_settings) +conn.initialize(logger) +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/1-psycopg2-connect.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/1-psycopg2-connect.md new file mode 100644 index 00000000..d5b39ddb --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/1-psycopg2-connect.md @@ -0,0 +1,42 @@ +--- +title: psycopg2.connect() +summary: psycopg2.connect() +author: Zhang Cuiping +date: 2021-10-11 +--- + +# psycopg2.connect() + +## 功能描述 + +此方法创建新的数据库会话并返回新的connection对象。 + +## 原型 + +``` +conn=psycopg2.connect(dbname="test",user="postgres",password="secret",host="127.0.0.1",port="5432") +``` + +## 参数 + +**表 1** psycopg2.connect参数 + +| **关键字** | **参数说明** | +| :---------- | :------------------------------------ | +| dbname | 数据库名称 | +| user | 用户名 | +| password | 密码 | +| host | 数据库IP地址,默认为UNIX socket类型。 | +| port | 连接端口号,默认为5432。 | +| sslmode | ssl模式,ssl连接时用。 | +| sslcert | 客户端证书路径,ssl连接时用。 | +| sslkey | 客户端密钥路径,ssl连接时用。 | +| sslrootcert | 根证书路径,ssl连接时用。 | + +## 返回值 + +connection对象(连接MogDB数据库实例的对象)。 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/10-connection-close.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/10-connection-close.md new file mode 100644 index 00000000..ce0a7167 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/10-connection-close.md @@ -0,0 +1,32 @@ +--- +title: connection.close() +summary: connection.close() +author: Zhang Cuiping +date: 2021-10-11 +--- + +# connection.close() + +## 功能描述 + +此方法关闭数据库连接。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** 此方法关闭数据库连接,并不自动调用commit()。如果只是关闭数据库连接而不调用commit()方法,那么所有更改将会丢失。 + +## 原型 + +``` +connection.close() +``` + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/2-connection-cursor.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/2-connection-cursor.md new file mode 100644 index 00000000..e97c1291 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/2-connection-cursor.md @@ -0,0 +1,37 @@ +--- +title: connection.cursor() +summary: connection.cursor() +author: Zhang Cuiping +date: 2021-10-11 +--- + +# connection.cursor() + +## 功能描述 + +此方法用于返回新的cursor对象。 + +## 原型 + +``` +cursor(name=None, cursor_factory=None, scrollable=None, withhold=False) +``` + +## 参数 + +**表 1** connection.cursor参数 + +| **关键字** | **参数说明** | +| :------------- | :--------------------------------- | +| name | cursor名称,默认为None。 | +| cursor_factory | 用于创造非标准cursor,默认为None。 | +| scrollable | 设置SCROLL选项,默认为None。 | +| withhold | 设置HOLD选项,默认为False。 | + +## 返回值 + +cursor对象(用于整个数据库使用Python编程的cursor)。 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/3-cursor-execute-query-vars-list.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/3-cursor-execute-query-vars-list.md new file mode 100644 index 00000000..bd3230ce --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/3-cursor-execute-query-vars-list.md @@ -0,0 +1,35 @@ +--- +title: cursor.execute(query,vars_list) +summary: cursor.execute(query,vars_list) +author: Zhang Cuiping +date: 2021-10-11 +--- + +# cursor.execute(query,vars_list) + +## 功能描述 + +此方法执行被参数化的SQL语句(即占位符,而不是SQL文字)。psycopg2模块支持用%s标志的占位符。 + +## 原型 + +``` +curosr.execute(query,vars_list) +``` + +## 参数 + +**表 1** curosr.execute参数 + +| **关键字** | **参数说明** | +| :--------- | :------------------------------ | +| query | 待执行的sql语句。 | +| vars_list | 变量列表,匹配query中%s占位符。 | + +## 返回值 + +无 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/4-curosr-executemany-query-vars-list.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/4-curosr-executemany-query-vars-list.md new file mode 100644 index 00000000..2f369f9a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/4-curosr-executemany-query-vars-list.md @@ -0,0 +1,35 @@ +--- +title: curosr.executemany(query,vars_list) +summary: curosr.executemany(query,vars_list) +author: Zhang Cuiping +date: 2021-10-11 +--- + +# curosr.executemany(query,vars_list) + +## 功能描述 + +此方法执行SQL命令所有参数序列或序列中的SQL映射。 + +## 原型 + +``` +curosr.executemany(query,vars_list) +``` + +## 参数 + +**表 1** curosr.executemany参数 + +| **关键字** | **参数说明** | +| :--------- | :------------------------------ | +| query | 待执行的SQL语句。 | +| vars_list | 变量列表,匹配query中%s占位符。 | + +## 返回值 + +无 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/5-connection-commit.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/5-connection-commit.md new file mode 100644 index 00000000..506c0ed7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/5-connection-commit.md @@ -0,0 +1,32 @@ +--- +title: connection.commit() +summary: connection.commit() +author: Zhang Cuiping +date: 2021-10-11 +--- + +# connection.commit() + +## 功能描述 + +此方法将当前挂起的事务提交到数据库。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** 默认情况下,Psycopg在执行第一个命令之前打开一个事务:如果不调用commit(),任何数据操作的效果都将丢失。 + +## 原型 + +``` +connection.commit() +``` + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/6-connection-rollback.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/6-connection-rollback.md new file mode 100644 index 00000000..128f2c1f --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/6-connection-rollback.md @@ -0,0 +1,32 @@ +--- +title: connection.rollback() +summary: connection.rollback() +author: Zhang Cuiping +date: 2021-10-11 +--- + +# connection.rollback() + +## 功能描述 + +此方法回滚当前挂起事务。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** 执行关闭连接“close()”而不先提交更改“commit()”将导致执行隐式回滚。 + +## 原型 + +``` +connection.rollback() +``` + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/7-cursor-fetchone.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/7-cursor-fetchone.md new file mode 100644 index 00000000..d92caf2b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/7-cursor-fetchone.md @@ -0,0 +1,30 @@ +--- +title: cursor.fetchone() +summary: cursor.fetchone() +author: Zhang Cuiping +date: 2021-10-11 +--- + +# cursor.fetchone() + +## 功能描述 + +此方法提取查询结果集的下一行,并返回一个元组。 + +## 原型 + +``` +cursor.fetchone() +``` + +## 参数 + +无 + +## 返回值 + +单个元组,为结果集的第一条结果,当没有更多数据可用时,返回为“None”。 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/8-cursor-fetchall.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/8-cursor-fetchall.md new file mode 100644 index 00000000..ce2b8462 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/8-cursor-fetchall.md @@ -0,0 +1,30 @@ +--- +title: cursor.fetchall() +summary: cursor.fetchall() +author: Zhang Cuiping +date: 2021-10-11 +--- + +# cursor.fetchall() + +## 功能描述 + +此方法获取查询结果的所有(剩余)行,并将它们作为元组列表返回。 + +## 原型 + +``` +cursor.fetchall() +``` + +## 参数 + +无 + +## 返回值 + +元组列表,为结果集的所有结果。空行时则返回空列表。 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/9-cursor-close.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/9-cursor-close.md new file mode 100644 index 00000000..0f20b0f3 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/11-psycopg-api-reference/9-cursor-close.md @@ -0,0 +1,30 @@ +--- +title: cursor.close() +summary: cursor.close() +author: Zhang Cuiping +date: 2021-10-11 +--- + +# cursor.close() + +## 功能描述 + +此方法关闭当前连接的游标。 + +## 原型 + +``` +cursor.close() +``` + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +请参见[示例:常用操作](../../../../developer-guide/dev/4.1-psycopg-based-development/10.1-example-common-operations.md)。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/2-psycopg-package.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/2-psycopg-package.md new file mode 100644 index 00000000..af6a2539 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/2-psycopg-package.md @@ -0,0 +1,17 @@ +--- +title: Psycopg包 +summary: Psycopg包 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# Psycopg包 + +访问[openGauss下载页面](https://opengauss.org/zh/download.html)获取。 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/psycopg-package.png) + +解压后有两个文件夹: + +- psycopg2:psycopg2库文件。 +- lib:lib库文件。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/3.1-development-process.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/3.1-development-process.md new file mode 100644 index 00000000..149bfb6b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/3.1-development-process.md @@ -0,0 +1,12 @@ +--- +title: 开发流程 +summary: 开发流程 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 开发流程 + +**图 1** psycopg2开发应用程序的流程 + +![ODBC开发应用程序的流程](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/development-process-1.png) diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/4-loading-a-driver.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/4-loading-a-driver.md new file mode 100644 index 00000000..d2c79b5a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/4-loading-a-driver.md @@ -0,0 +1,21 @@ +--- +title: 加载驱动 +summary: 加载驱动 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 加载驱动 + +- 在使用驱动之前,需要做如下操作: + + 1. 先解压版本对应驱动包,使用root用户将psycopg2拷贝到python安装目录下的site-packages文件夹下。 + 2. 修改psycopg2目录权限为755。 + 3. 将psycopg2目录添加到环境变量$PYTHONPATH,并使之生效。 + 4. 对于非数据库用户,需要将解压后的lib目录,配置在LD_LIBRARY_PATH中。 + +- 在创建数据库连接之前,需要先加载如下数据库驱动程序: + + ``` + import psycopg2 + ``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/5.1-connecting-to-a-database.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/5.1-connecting-to-a-database.md new file mode 100644 index 00000000..43e237a3 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/5.1-connecting-to-a-database.md @@ -0,0 +1,11 @@ +--- +title: 连接数据库 +summary: 连接数据库 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 连接数据库 + +1. 使用psycopg2.connect函数获得connection对象。 +2. 使用connection对象创建cursor对象。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/6-executing-sql-statements.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/6-executing-sql-statements.md new file mode 100644 index 00000000..c53b2464 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/6-executing-sql-statements.md @@ -0,0 +1,11 @@ +--- +title: 执行SQL语句 +summary: 执行SQL语句 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 执行SQL语句 + +1. 构造操作语句,使用%s作为占位符,执行时psycopg2会用参数值智能替换掉占位符。可以添加RETURNING子句,来得到自动生成的字段值。 +2. 使用cursor.execute方法来操作一行,使用cursor.executemany方法来操作多行。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/7-processing-the-result-set.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/7-processing-the-result-set.md new file mode 100644 index 00000000..4e06c48e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/7-processing-the-result-set.md @@ -0,0 +1,11 @@ +--- +title: 处理结果集 +summary: 处理结果集 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 处理结果集 + +1. cursor.fetchone():这种方法提取查询结果集的下一行,返回一个序列,没有数据可用时则返回空。 +2. cursor.fetchall():这个例程获取所有查询结果(剩余)行,返回一个列表。空行时则返回空列表。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/8-closing-the-connection.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/8-closing-the-connection.md new file mode 100644 index 00000000..ca2ca8df --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/8-closing-the-connection.md @@ -0,0 +1,12 @@ +--- +title: 关闭连接 +summary: 关闭连接 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 关闭连接 + +在使用数据库连接完成相应的数据操作后,需要关闭数据库连接。关闭数据库连接可以直接调用其close方法,如connection.close()。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-caution.gif) **注意:** 此方法关闭数据库连接,并不自动调用commit()。如果只是关闭数据库连接而不调用commit()方法,那么所有更改将会丢失。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/9-connecting-to-the-database-using-ssl.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/9-connecting-to-the-database-using-ssl.md new file mode 100644 index 00000000..9c9859ec --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/4.1-psycopg-based-development/9-connecting-to-the-database-using-ssl.md @@ -0,0 +1,37 @@ +--- +title: 连接数据库 +summary: 连接数据库 +author: Zhang Cuiping +date: 2021-10-11 +--- + +# 连接数据库(SSL方式) + +用户通过psycopy2连接MogDB服务器时,可以通过开启SSL加密客户端和服务器之间的通讯。在使用SSL时,默认用户已经获取了服务端和客户端所需要的证书和私钥文件,关于证书等文件的获取请参考Openssl相关文档和命令。 + +1. 使用*.ini文件(python的configparser包可以解析这种类型的配置文件)保存数据库连接的配置信息。 + +2. 在连接选项中添加SSL连接相关参数:sslmode,sslcert,sslkey,sslrootcert。 + + - sslmode:可选项见[表1](#table1.1)。 + + - sslcert:客户端证书路径。 + + - sslkey:客户端密钥路径。 + + - sslrootcert:根证书路径。 + +3. 使用psycopg2.connect函数获得connection对象。 + +4. 使用connection对象创建cursor对象。 + +**表 1** sslmode的可选项及其描述 + +| sslmode | 是否会启用SSL加密 | 描述 | +| :---------- | :---------------- | :----------------------------------------------------------- | +| disable | 否 | 不适用SSL安全连接。 | +| allow | 可能 | 如果数据库服务器要求使用,则可以使用SSL安全加密连接,但不验证数据库服务器的真实性。 | +| prefer | 可能 | 如果数据库支持,那么首选使用SSL连接,但不验证数据库服务器的真实性。 | +| require | 是 | 必须使用SSL安全连接,但是只做了数据加密,而并不验证数据库服务器的真实性。 | +| verify-ca | 是 | 必须使用SSL安全连接。 | +| verify-full | 是 | 必须使用SSL安全连接,目前MogDB 暂不支持。 | \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/dev/5-commissioning.md b/product/zh/docs-mogdb/v3.1/developer-guide/dev/5-commissioning.md new file mode 100644 index 00000000..93d569c0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/dev/5-commissioning.md @@ -0,0 +1,40 @@ +--- +title: 调试 +summary: 调试 +author: Guo Huan +date: 2021-04-27 +--- + +# 调试 + +用户可以根据自己的需要,通过修改实例数据目录下的postgresql.conf文件中特定的配置参数来控制日志的输出,从而更好的了解数据库的运行状态。 + +可调整的配置参数请参见[表1](#配置参数)。 + +**表 1** 配置参数 + +| 参数名称 | 描述 | 取值范围 | 备注 | +| :--------------------------------- | :------------------------- | :---------------------------- | :---------------------------| +| client_min_messages | 配置发送到客户端信息的级别。 | - DEBUG5
- DEBUG4
- DEBUG3
- DEBUG2
- DEBUG1
- LOG
- NOTICE
WARNING
- ERROR
- FATAL
- PANIC
默认值: NOTICE 。 | 设置级别后,发送到客户端的信息包含所设级别及以下所有低级别会发送的信息。级别越低,发送的信息越少。 | +| log_min_messages | 配置写到服务器日志里信息的级别。 | - DEBUG5
- DEBUG4
- DEBUG3
- DEBUG2
- DEBUG1
- INFO
- NOTICE
- WARNING
- ERROR
- LOG
- FATAL
- PANIC
默认值: WARNING。 | 指定某一级别后,写到日志的信息包含所有更高级别会输出的信息。级别越高,服务器日志的信息越少。 | +| log_min_error_statement | 配置写到服务器日志中错误SQL语句的级别。 | - DEBUG5
- DEBUG4
- DEBUG3
- DEBUG2
- DEBUG1
- INFO
- NOTICE
- WARNING
- ERROR
- FATAL
- PANIC
缺省值: ERROR。 | 所有导致一个特定级别(或者更高级别)错误的SQL语句都将记录在服务器日志中。只有系统管理员可以修改该参数。 | +| log_min_duration_statement | 配置语句执行持续的最短时间。如果某个语句的持续时间大于或者等于设置的毫秒数,则会在日志中记录该语句及其持续时间。打开这个选项可以方便地跟踪需要优化的查询。 | INT类型。
默认值: 30min。
单位: 毫秒。 | 设置为-1表示关闭这个功能。只有系统管理员可以修改该参数。 | +| log_connections/log_disconnections | 配置是否在每次会话连接或结束时向服务器日志里打印一条信息。 | - on: 每次会话连接或结束时向日志里打印一条信息。
- off: 每次会话连接或结束时不向日志里打印信息。
默认值: off。 | - | +| log_duration | 配置是否记录每个已完成语句的持续时间。 | - on: 记录每个已完成语句的持续时间。
- off: 不记录已完成语句的持续时间。默认值: on 。 | 只有系统管理员可以修改该参数。 | +| log_statement | 配置日志中记录哪些SQL语句。 | - none: 不记录任何SQL语句。
- ddl: 记录数据定义语句。
- mod: 记录数据定义语句和数据操作语句。
- all : 记录所有语句。
默认值: none。 | 只有系统管理员可以修改该参数。 | +| log_hostname | 配置是否记录主机名。 | - on: 记录主机名。
- off: 不记录主机名。
默认值: off。 | 缺省时,连接日志只记录所连接主机的IP地址。打开这个选项会同时记录主机名。该参数同时影响 "查看审计结果"、GS_WLM_SESSION_HISTORY、PG_STAT_ACTIVITY和log_line_prefix参数。 | + +上表有关参数级别的说明请参见[表2](#日志级别参数说明)。 + +**表 2** 日志级别参数说明 + +| 级别 | 说明 | +| :--------- | :--------------------------------------------------------------------- | +| DEBUG[1-5] | 提供开发人员使用的信息。5级为最高级别,依次类推,1级为最低级别。 | +| INFO | 提供用户隐含要求的信息。如在VACUUM VERBOSE过程中的信息。 | +| NOTICE | 提供可能对用户有用的信息。如长标识符的截断,作为主键一部分创建的索引。 | +| WARNING | 提供给用户的警告。如在事务块范围之外的COMMIT。 | +| ERROR | 报告导致当前命令退出的错误。 | +| LOG | 报告一些管理员感兴趣的信息。如检查点活跃性。 | +| FATAL | 报告导致当前会话终止的原因。 | +| PANIC | 报告导致所有会话退出的原因。 | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/1-oracle_fdw.md b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/1-oracle_fdw.md new file mode 100644 index 00000000..2f0754aa --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/1-oracle_fdw.md @@ -0,0 +1,51 @@ +--- +title: oracle_fdw +summary: oracle_fdw +author: Zhang Cuiping +date: 2021-05-17 +--- + +# oracle_fdw + +oracle_fdw(foreign data wrapper for oracle)用于Oracle的外部数据包装器,是一款开源插件。MogDB基于开源的[oracle_fdw Release 2.2.0版本](https://github.com/laurenz/oracle_fdw/archive/ORACLE_FDW_2_2_0.tar.gz)进行开发适配。 + +编译和使用oracle_fdw需要环境上包含Oracle的开发包,所以MogDB默认不编译oracle_fdw,下面依次介绍如何编译和使用oracle_fdw。 + +## 编译oracle_fdw + +编译oracle_fdw需要安装Oracle的开发库和头文件。 + +选择合适的运行环境和版本,下载**Basic Package**和**SDK Package**并安装。另外**SQLPlus Package**是Oracle的客户端工具,也可以根据需要安装,用于连接Oracle Server进行测试。 + +安装好开发包后,就可以开始编译oracle_fdw了。编译时需要在执行**configure**时,加入`--enable-oracle-fdw`选项。后续按照正常的MogDB编译方式编译即可。 + +编译完成后,编译产物为**oracle_fdw.so**,位于安装目录的`lib/postgresql/`下。oracle_fdw相关的sql文件和control文件,位于安装目录的`share/postgresql/extension/`下。 + +如果编译安装时,没有加入`--enable-oracle-fdw`选项,可以在MogDB安装完成后,再次编译oracle_fdw,然后手动将编译产物`oracle_fdw.so`放到对应的安装目录`lib/postgresql/`,将`oracle_fdw-1.0-1.1.sql`、`oracle_fdw-1.1.sql`、`oracle_fdw.control`放到对应的安装目录`share/postgresql/extension/`即可。 + +## 使用oracle_fdw + +- 使用oracle_fdw需要连接Oracle,Oracle server请自行安装。 +- 加载oracle_fdw扩展:**CREATE EXTENSION oracle_fdw** +- 创建服务器对象:**CREATE SERVER** +- 创建用户映射:**CREATE USER MAPPING** +- 创建外表:**CREATE FOREIGN TABLE** + + 外表的表结构需要与Oracle数据库中的表结构保持一致。注意Oracle server侧的表的第一个字段必须具有唯一性约束(如PRIMARY KEY、UNIQUE等)。 +- 对外表做正常的操作,如**INSERT**、**UPDATE**、**DELETE**、**SELECT**、**EXPLAIN**、**ANALYZE**、**COPY**等。 +- 删除外表:**DROP FOREIGN TABLE** +- 删除用户映射:**DROP USER MAPPING** +- 删除服务器对象:**DROP SERVER** +- 删除扩展:**DROP EXTENSION oracle_fdw** + +## 常见问题 + +- 在MogDB上建立外表时,不会在Oracle数据库中同步建表,需要自行在Oracle数据库中建表。 +- 执行**CREATE USER MAPPING**时使用的Oracle用户需要有远程连接Oracle数据库及对表相关操作的权限。使用外表前,可以在MogDB server所在的机器上,使用Oracle的客户端,使用对应的用户名密码确认能否成功连接Oracle并进行操作。 +- 执行**CREATE EXTENSION oracle_fdw;**时,出现`libclntsh.so: cannot open shared object file: No such file or directory`。原因是Oracle的开发库libclntsh.so不在系统的相关路径中,可以先找到libclntsh.so的具体路径,然后将该so文件所在的文件夹加到`/etc/ld.so.conf`中。比如libclntsh.so的路径为`/usr/lib/oracle/11.2/client64/lib/libclntsh.so.11.1`,那么就将该文件的路径`/usr/lib/oracle/11.2/client64/lib/`加到`/etc/ld.so.conf`文件末尾。然后执行`ldconfig`使修改生效即可。注意此操作需要**root**权限。 + +## 注意事项 + +- 两个Oracle外表间的**SELECT JOIN**不支持下推到Oracle server执行,会被分成两条SQL语句传递到Oracle执行,然后在MogDB处汇总处理结果。 +- 不支持**IMPORT FOREIGN SCHEMA**语法。 +- 不支持对外表进行**CREATE TRIGGER**操作。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/2-mysql_fdw.md b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/2-mysql_fdw.md new file mode 100644 index 00000000..45cc996d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/2-mysql_fdw.md @@ -0,0 +1,51 @@ +--- +title: mysql_fdw +summary: mysql_fdw +author: Zhang Cuiping +date: 2021-05-17 +--- + +# mysql_fdw + +mysql_fdw是一款开源插件。MogDB基于开源的[mysql_fdw Release 2.5.3版本](https://github.com/EnterpriseDB/mysql_fdw/archive/REL-2_5_3.tar.gz)进行开发适配。 + +编译和使用mysql_fdw需要环境上包含MariaDB的开发包,所以MogDB默认不编译mysql_fdw,下面依次介绍如何编译和使用mysql_fdw。 + +## 编译mysql_fdw + +编译mysql_fdw需要安装MariaDB的开发库和头文件,推荐使用MariaDB的[官方源](http://downloads.mariadb.org/mariadb/repositories)进行安装。 + +配置好源后,使用**yum install MariaDB-devel MariaDB-shared**安装相关开发库。另外**MariaDB-client**是MariaDB的客户端工具,也可以根据需要安装,用于连接MariaDB进行测试。 + +安装好开发包后,就可以开始编译mysql_fdw了。编译时需要在执行**configure**时,加入`--enable-mysql-fdw`选项。后续按照正常的MogDB编译方式编译即可。 + +编译完成后,编译产物为**mysql_fdw.so**,位于安装目录的**lib/postgresql/**下。mysql_fdw相关的sql文件和control文件,位于安装目录的**share/postgresql/extension/**下。 + +如果编译安装时,没有加入`--enable-mysql-fdw`选项,可以在MogDB安装完成后,再次编译mysql_fdw,然后手动将编译产物`mysql_fdw.so`放到对应的安装目录**lib/postgresql/**,将**mysql_fdw-1.0-1.1.sql、mysql_fdw-1.1.sql、mysql_fdw-1.0.sql、mysql_fdw.control**放到对应的安装目录**share/postgresql/extension/**即可。 + +## 使用mysql_fdw + +- 使用mysql_fdw需要连接MariaDB或者MySQL Server,MariaDB或MySQL Server请自行安装。 +- 加载mysql_fdw扩展:**CREATE EXTENSION mysql_fdw;** +- 创建服务器对象:**CREATE SERVER** +- 创建用户映射:**CREATE USER MAPPING** +- 创建外表:**CREATE FOREIGN TABLE** + + 外表的表结构需要与MySQL/MariaDB侧的表结构保持一致。注意MySQL/MariaDB侧的表的第一个字段必须具有唯一性约束(如PRIMARY KEY、UNIQUE等)。 +- 对外表做正常的操作,如**INSERT**、**UPDATE**、**DELETE**、**SELECT**、**EXPLAIN**、**ANALYZE**、**COPY**等。 +- 删除外表:**DROP FOREIGN TABLE** +- 删除用户映射:**DROP USER MAPPING** +- 删除服务器对象:**DROP SERVER** +- 删除扩展:**DROP EXTENSION mysql_fdw;** + +## 常见问题 + +- 在MogDB上建立外表时,不会同步在MariaDB/MySQL Server上建表,需要自己利用MariaDB/MySQL Server的客户端连接MariaDB/MySQL Server建表。 +- 创建USER MAPPING时使用的MariaDB/MySQL Server用户需要有远程连接MariaDB/MySQL Server及对表相关操作的权限。使用外表前,可以在MogDB server所在的机器上,使用MariaDB/MySQL Server的客户端,使用对应的用户名密码确认能否成功连接MariaDB/MySQL Server并进行操作。 +- 对外表执行DML操作时,出现**Can't initialize character set SQL_ASCII (path: compiled_in)**错误。由于MariaDB不支持**SQL_ASCII**编码格式,目前只能通过修改MogDB database的编码格式解决该问题。修改database编码格式的方式为**update pg_database set encoding = pg_char_to_encoding('UTF-8') where datname = 'postgres';** datname根据实际情况填写。注意修改完编码格式后,需要重新开启一个gsql会话,才能使mysql_fdw使用更新后的参数。也可以通过在执行**gs\_initdb**时,使用`--locale=LOCALE`,指定默认的编码格式为**非SQL_ASCII**编码。 + +## 注意事项 + +- 两个mysql外表间的**SELECT JOIN**不支持下推到MariaDB/MySQL Server执行,会被分成两条SQL语句传递到MariaDB/MySQL Server执行,然后在MogDB处汇总处理结果。 +- 不支持**IMPORT FOREIGN SCHEMA**语法。 +- 不支持对外表进行**CREATE TRIGGER**操作。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/3-postgres_fdw.md b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/3-postgres_fdw.md new file mode 100644 index 00000000..4ba9518a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/3-postgres_fdw.md @@ -0,0 +1,37 @@ +--- +title: postgres_fdw +summary: postgres_fdw +author: Zhang Cuiping +date: 2021-05-17 +--- + +# postgres_fdw + +postgres_fdw是一款开源插件,其代码随PostgreSQL源码一同发布。MogDB基于开源的PostgreSQL 9.4.26版本中的postgres_fdw源码进行开发适配。 + +postgres_fdw插件默认参与编译,使用安装包安装好MogDB后,可直接使用postgres_fdw,无须其他操作。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**:当前postgres_fdw仅支持MogDB连接MogDB,不支持MogDB连接PostgreSQL。 + +## 使用postgres_fdw + +- 加载postgres_fdw扩展:**CREATE EXTENSION postgres_fdw;** +- 创建服务器对象:**CREATE SERVER** +- 创建用户映射:**CREATE USER MAPPING** +- 创建外表:**CREATE FOREIGN TABLE**外表的表结构需要与远端MogDB侧的表结构保持一致。 +- 对外表做正常的操作,如**INSERT**、**UPDATE**、**DELETE**、**SELECT**、**EXPLAIN**、**ANALYZE**、**COPY**等。 +- 删除外表:**DROP FOREIGN TABLE** +- 删除用户映射:**DROP USER MAPPING** +- 删除服务器对象:**DROP SERVER** +- 删除扩展:**DROP EXTENSION postgres_fdw;** + +## 常见问题 + +- 在MogDB上建立外表时,不会同步在远端的MogDB上建表,需要自己利用客户端连接远端MogDB建表。 +- 执行**CREATE USER MAPPING**时使用的MogDB用户需要有远程连接MogDB及对表相关操作的权限。使用外表前,可以在本地机器上,使用gsql的客户端,使用对应的用户名密码确认能否成功连接远端MogDB并进行操作。 + +## 注意事项 + +- 两个postgres_fdw外表间的**SELECT JOIN**不支持下推到远端MogDB执行,会被分成两条SQL语句传递到远端MogDB执行,然后在本地汇总处理结果。 +- 不支持**IMPORT FOREIGN SCHEMA**语法。 +- 不支持对外表进行**CREATE TRIGGER**操作。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/dblink.md b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/dblink.md new file mode 100644 index 00000000..8cee4e6d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/dblink.md @@ -0,0 +1,79 @@ +--- +title: dblink +summary: dblink +author: Guo Huan +date: 2021-10-19 +--- + +# dblink + +dblink是一个可以在一个MogDB数据库会话中连接到其它MogDB数据库的工具,同libpq支持的链接参数一致,可参考[链接参数](../../developer-guide/dev/4-development-based-on-libpq/link-parameters.md)。MogDB默认不编译dblink,下面依次介绍如何编译和使用dblink。 + +## 编译dblink + +当前dblink的源码放在[contrib/dblink](https://gitee.com/opengauss/openGauss-server/tree/master/contrib/dblink)目录中。在编译安装完MogDB数据库之后,如果用户需要使用dblink,只需要进入上述目录执行如下即可完成dblink的编译安装。 + +```bash +make +make install +``` + +## 常用的dblink函数 + +- 加载dblink扩展 + + ```sql + CREATE EXTENSION dblink; + ``` + +- 打开一个到远程数据库的持久连接 + + ```sql + SELECT dblink_connect(text connstr); + ``` + +- 关闭一个到远程数据库的持久连接 + + ```sql + SELECT dblink_disconnect(); + ``` + +- 在远程数据库执行查询 + + ```sql + SELECT * FROM dblink(text connstr, text sql); + ``` + +- 在远程数据库执行命令 + + ```sql + SELECT dblink_exec(text connstr, text sql); + ``` + +- 返回所有打开的命名dblink连接的名称 + + ```sql + SELECT dblink_get_connections(); + ``` + +- 发送一个异步查询到远程数据库 + + ```sql + SELECT dblink_send_query(text connname, text sql); + ``` + +- 检查连接是否正在忙于一个异步查询 + + ```sql + SELECT dblink_is_busy(text connname); + ``` + +- 删除扩展 + + ```sql + DROP EXTENSION dblink; + ``` + +## 注意事项 + +目前dblink仅支持MogDB数据库访问另一个MogDB数据库,不支持MogDB数据库访问PostgreSQL数据库。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/fdw-introduction.md b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/fdw-introduction.md new file mode 100644 index 00000000..4e8838c7 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/fdw-introduction.md @@ -0,0 +1,10 @@ +--- +title: 介绍 +summary: 介绍 +author: Zhang Cuiping +date: 2021-05-17 +--- + +# 介绍 + +MogDB的fdw实现的功能是各个MogDB数据库及远程数据库之间的跨库操作。目前支持的远程服务器类型包括Oracle、MySQL(MariaDB)、PostgreSQL/openGauss/MogDB(postgres_fdw)、file_fdw 、dblink。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/file_fdw.md b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/file_fdw.md new file mode 100644 index 00000000..b0f235c3 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/foreign-data-wrapper/file_fdw.md @@ -0,0 +1,79 @@ +--- +title: file_fdw +summary: file_fdw +author: Guo Huan +date: 2021-10-19 +--- + +# file_fdw + +file_fdw模块提供了外部数据封装器file_fdw,可以用来在服务器的文件系统中访问数据文件。数据文件必须是COPY FROM可读的格式;具体可参照[COPY](../../reference-guide/sql-syntax/COPY.md)语句的介绍。访问这样的数据文件当前只是可读的。当前不支持对该数据文件的写入操作。 + +当前MogDB会默认编译file_fdw,在initdb的时候会在pg_catalog schema中创建该插件。 + +使用file_fdw创建的外部表可以有下列选项: + +- **filename** + + 指定要读取的文件,必需的参数,且必须是一个绝对路径名。 + +- **format** + + 远端server的文件格式,支持text/csv/binary三种格式,和COPY语句的FORMAT选项相同。 + +- **header** + + 指定的文件是否有标题行,与COPY语句的HEADER选项相同。 + +- **delimiter** + + 指定文件的分隔符,与COPY的DELIMITER选项相同。 + +- **quote** + + 指定文件的引用字符,与COPY的QUOTE选项相同。 + +- **escape** + + 指定文件的转义字符,与COPY的ESCAPE选项相同。 + +- **null** + + 指定文件的null字符串,与COPY的NULL选项相同。 + +- **encoding** + + 指定文件的编码,与COPY的ENCODING选项相同。 + +- **force_not_null** + + 这是一个布尔选项。如果为真,则声明字段的值不应该匹配空字符串(也就是, 文件级别null选项)。与COPY的FORCE_NOT_NULL选项里的字段相同。 + +
+ +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**注意:** +> +> - file_fdw不支持COPY的OIDS和FORCE_QUOTE选项。 +> +> - 注意这些选项只能为外部表或它的字段声明,不是在file_fdw外部数据封装器的选项里,也不是在使用该封装器的服务器或用户映射的选项里。 +> +> - 修改表级别的选项需要系统管理员权限,因为安全原因:只有系统管理员用户能够决定读哪个文件。 +> +> - 对于一个使用file_fdw的外部表,EXPLAIN显示要读取的文件名。除非指定了COSTS OFF,否则也显示文件大小(字节计)。 + +## 使用file_fdw + +- 使用file_fdw需要指定要读取的文件,请先准备好该文件,并让数据库有读取权限。 +- 创建服务器对象:**CREATE SERVER** +- 创建用户映射:**CREATE USER MAPPING** +- 创建外表:**CREATE FOREIGN TABLE** + + 外表的表结构需要与指定的文件的数据保持一致。 +- 对外表做查询操作,写操作不被允许。 +- 删除外表:**DROP FOREIGN TABLE** +- 删除用户映射:**DROP USER MAPPING** +- 删除服务器对象:**DROP SERVER** + +## 注意事项 + +- 不支持**DROP EXTENSION file_fdw**操作。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/logical-decoding/1-logical-decoding.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/logical-decoding/1-logical-decoding.md new file mode 100644 index 00000000..0c4eb3bc --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/logical-decoding/1-logical-decoding.md @@ -0,0 +1,56 @@ +--- +title: 逻辑解码概述 +summary: 逻辑解码概述 +author: Zhang Cuiping +date: 2021-05-10 +--- + +# 逻辑解码概述 + +## 功能描述 + +MogDB对数据复制能力的支持情况为: + +支持通过数据迁移工具定期向异构数据库(如Oracle等)进行数据同步,不具备实时数据复制能力。不足以支撑与异构数据库间并网运行实时数据同步的诉求。 + +MogDB提供了逻辑解码功能,通过反解xlog的方式生成逻辑日志。目标数据库解析逻辑日志以实时进行数据复制。具体如图1所示。逻辑复制降低了对目标数据库的形态限制,支持异构数据库、同构异形数据库对数据的同步,支持目标库进行数据同步期间的数据可读写,数据同步时延低。 + +**图1** 逻辑复制 + +![image-20210512102853986](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/logical-decoding-1.png) + +逻辑复制由两部分组成:逻辑解码和数据复制。逻辑解码会输出以事务为单位组织的逻辑日志。业务或数据库中间件将会对逻辑日志进行解析并最终实现数据复制。MogDB当前只提供逻辑解码功能,因此本章节只涉及逻辑解码的说明。 + +逻辑解码为逻辑复制提供事务解码的基础能力,MogDB使用SQL函数接口进行逻辑解码。此方法调用方便,不需使用工具,对接外部工具接口也比较清晰,不需要额外适配。 + +由于逻辑日志是以事务为单位的,在事务提交后才能输出,且逻辑解码是由用户驱动的;因此为了防止事务开始时的xlog被系统回收,或所需的事务信息被VACUUM回收,MogDB新增了逻辑复制槽,用于阻塞xlog的回收。 + +一个逻辑复制槽表示一个更改流,这些更改可以在其它数据库中以它们在原数据库上产生的顺序被重播。逻辑复制槽,由每个逻辑日志的获取者维护一个。 + +## 注意事项 + +- 不支持DDL语句解码,在执行特定的DDL语句(例如普通表truncate或分区表exchange)时,可能造成解码数据丢失。 +- 不支持列存、数据页复制的解码。 +- 不支持级联备机进行逻辑解码。 +- 当执行DDL语句(如alter table)后,该DDL语句前尚未解码的物理日志可能会丢失。 +- 单条元组大小不超过1GB,考虑解码结果可能大于插入数据,因此建议单条元组大小不超过500MB。 +- MogDB支持解码的数据类型为:INTEGER、BIGINT、SMALLINT、TINYINT、SERIAL、SMALLSERIAL、BIGSERIAL、FLOAT、DOUBLE PRECISION、DATE、TIME[WITHOUT TIME ZONE]、TIMESTAMP[WITHOUT TIME ZONE]、CHAR(n)、VARCHAR(n)、TEXT。 +- 如果需要ssl连接需要保证前置设置GUC参数ssl=on。 +- 逻辑复制槽名称必须小于64个字符,且只包含小写字母、数字或者下划线中的一种或几种。 +- 当前逻辑复制不支持MOT特性。 +- 当逻辑复制槽所在数据库被删除后,这些复制槽变为不可用状态,需要用户手动删除。 +- 仅支持utf-8字符集。 +- 对多库的解码需要分别在库内创建流复制槽并开始解码,每个库的解码都需要单独扫一遍日志。 +- 不支持强起,强起后需要重新全量导出数据。 +- 备机解码时,switchover和failover时可能出现解码数据变多,需用户手动过滤。Qurem协议下,switchover和failover选择升主的备机,需要与当前主机日志同步。 +- 不允许主备,多个备机同时使用同一个复制槽解码,否则会产生数据不一致。 +- 只支持主机创建删除复制槽。 +- 数据库故障重启或逻辑复制进程重启后,解码数据存在重复,用户需自己过滤。 +- 计算机内核故障后,解码存在乱码,需手动或自动过滤。 +- 当前备机逻辑解码,不支持开启极致RTO。 +- 请确保在创建逻辑复制槽过程中长事务未启动,启动长事务会阻塞逻辑复制槽的创建。 +- 不支持interval partition表复制。 +- 不支持全局临时表。 +- 在事务中执行DDL语句后,该DDL语句与之后的语句不会被解码。 +- 如需进行备机解码,需在对应主机上设置guc参数enable_slot_log = on。 +- 禁止在使用逻辑复制槽时在其他节点对该复制槽进行操作,删除复制槽进行操作的操作需在该复制槽停止解码后执行。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/logical-decoding/2-logical-decoding-by-sql-function-interfaces.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/logical-decoding/2-logical-decoding-by-sql-function-interfaces.md new file mode 100644 index 00000000..177fe3ef --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/logical-decoding/2-logical-decoding-by-sql-function-interfaces.md @@ -0,0 +1,85 @@ +--- +title: 使用SQL函数接口进行逻辑解码 +summary: 使用SQL函数接口进行逻辑解码 +author: Zhang Cuiping +date: 2021-05-10 +--- + +# 使用SQL函数接口进行逻辑解码 + +MogDB可以通过调用SQL函数,进行创建、删除、推进逻辑复制槽,获取解码后的事务日志。 + +## 前提条件 + +- 逻辑日志目前从主机节点中抽取,默认关闭SSL连接,如果进行逻辑复制,需要先配置GUC参数[ssl](../../../reference-guide/guc-parameters/3-connection-and-authentication/2-security-and-authentication.md#ssl)=on。 + + > **说明**: 为避免安全风险,请保证启用SSL连接。 + +- 设置GUC参数[wal_level](../../../reference-guide/guc-parameters/6-write-ahead-log/1-settings.md#wal_level)=logical。 + +- 设置GUC参数[max_replication_slots](../../../reference-guide/guc-parameters/7-ha-replication/1-sending-server.md#max_replication_slots)>每个节点所需的(物理流复制槽数+逻辑复制槽数)。 + + 物理流复制槽提供了一种自动化的方法来确保主节点在所有备节点或从备节点收到xlog之前,xlog不会被移除。也就是说物理流复制槽用于支撑主备节点HA。数据库所需要的物理流复制槽数为:备节点加从备的和与主节点之间的比例。例如,假设数据库的高可用方案为1主、1备、1从备,则所需物理流复制槽数为2。 + + 关于逻辑复制槽数,请按如下规则考虑。 + + - 一个逻辑复制槽只能解码一个Database的修改,如果需要解码多个Database,则需要创建多个逻辑复制槽。 + - 如果需要多路逻辑复制同步给多个目标数据库,在源端数据库需要创建多个逻辑复制槽,每个逻辑复制槽对应一条逻辑复制链路。 + +- 仅限初始用户和拥有REPLICATION权限的用户进行操作。三权分立关闭时数据库管理员可进行逻辑复制操作,三权分立开启时不允许数据库管理员进行逻辑复制操作。 + +- 目前默认不支持主备从部署模式。 + +## 操作步骤 + +1. 以数据库安装用户登录MogDB数据库主节点。 + +2. 使用如下命令通过连接默认数据库mogdb。 + + ```bash + gsql -d mogdb -p 16000 -r + ``` + + 其中,16000为数据库端口号,用户可根据实际情况替换。 + +3. 创建名称为slot1的逻辑复制槽。 + + ```sql + MogDB=# SELECT * FROM pg_create_logical_replication_slot('slot1', 'mppdb_decoding'); + slotname | xlog_position + ----------+--------------- + slot1 | 0/601C150 + (1 row) + ``` + +4. 在数据库中创建表t,并向表t中插入数据。 + + ```sql + MogDB=# CREATE TABLE t(a int PRIMARY KEY, b int); + MogDB=# INSERT INTO t VALUES(3,3); + ``` + +5. 读取复制槽slot1解码结果,解码条数为4096。 + + ```sql + MogDB=# SELECT * FROM pg_logical_slot_peek_changes('slot1', NULL, 4096); + location | xid | data + -----------+-------+------------------------------------------------------------------------------------------------------------------------------------------------- + ------------------------------------------- + 0/601C188 | 1010023 | BEGIN 1010023 + 0/601ED60 | 1010023 | COMMIT 1010023 CSN 1010022 + 0/601ED60 | 1010024 | BEGIN 1010024 + 0/601ED60 | 1010024 | {"table_name":"public.t","op_type":"INSERT","columns_name":["a","b"],"columns_type":["integer","integer"],"columns_val":["3","3"],"old_keys_name":[],"old_keys_type":[],"old_keys_val":[]} + 0/601EED8 | 1010024 | COMMIT 1010024 CSN 1010023 + (5 rows) + ``` + +6. 删除逻辑复制槽slot1。 + + ```sql + MogDB=# SELECT * FROM pg_drop_replication_slot('slot1'); + pg_drop_replication_slot + -------------------------- + + (1 row) + ``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/architecture.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/architecture.md new file mode 100644 index 00000000..d737feb6 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/architecture.md @@ -0,0 +1,16 @@ +--- +title: 架构 +summary: 架构 +author: Guo Huan +date: 2022-04-29 +--- + +# 架构 + +发布者上的更改会在它们发生时实时传送给订阅者。订阅者按照数据在发布者上被提交的顺序应用数据,这样任意单一订阅中的发布的事务一致性才能得到保证。 + +逻辑复制被构建在一种类似于物理流复制的架构上。它由“walsender”和“apply”进程实现。walsender进程开始对WAL的逻辑解码并且载入标准逻辑解码插件(pgoutput)。该插件把从WAL中读取的更改转换成逻辑复制协议并且根据发布说明过滤数据。然后数据会被连续地使用流复制协议传输到应用工作者,应用工作者会把数据映射到本地表并且以正确的事务顺序应用它们接收到的更改。 + +订阅者数据库上的应用进程总是将session_replication_role设置为replica运行,这会产生触发器和约束上通常的效果。 + +逻辑复制应用进程当前仅会引发行触发器,而不会引发语句触发器。不过,初始的表同步是以类似一个COPY命令的方式实现的,因此会引发INSERT的行触发器和语句触发器。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/configuration-settings.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/configuration-settings.md new file mode 100644 index 00000000..38fa5169 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/configuration-settings.md @@ -0,0 +1,14 @@ +--- +title: 配置设置 +summary: 配置设置 +author: Guo Huan +date: 2022-04-29 +--- + +# 配置设置 + +发布订阅要求设置一些配置选项。 + +在发布者端,wal_level必须被设置为logical,而max_replication_slots中设置的值必须至少是预期要连接的订阅数。max_wal_senders应该至少被设置为max_replication_slots加上同时连接的物理复制体的数量。 + +订阅者还要求max_replication_slots被设置。在这种情况下,它必须至少被设置为将被加入到该订阅者的订阅数。max_logical_replication_workers必须至少被设置为订阅数。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/conflicts.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/conflicts.md new file mode 100644 index 00000000..f7a711e4 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/conflicts.md @@ -0,0 +1,14 @@ +--- +title: 冲突处理 +summary: 冲突处理 +author: Guo Huan +date: 2022-04-29 +--- + +# 冲突处理 + +逻辑复制的行为类似于正常的DML操作,即便数据在订阅者节点本地被修改,逻辑复制也会根据收到的更改来更新数据。如果流入的数据违背了任何约束,复制将停止。这种情况被称为一个冲突。在复制UPDATE或DELETE操作时,缺失的数据将不会产生冲突并且这类操作将被简单地跳过。 + +冲突将会产生错误并且停止复制,它必须由用户手工解决。在订阅者的服务器日志中可以找到有关冲突的详细情况。 + +通过更改订阅者上的数据(这样它就不会与到来的数据发生冲突)或者跳过与已有数据冲突的事务可以解决这种冲突。通过调用pg_replication_origin_advance()函数可以跳过该事务,函数的参数是对应于该订阅名称的node_name以及一个位置。复制源头的当前位置可以在pg_replication_origin_status系统视图中看到。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/monitoring.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/monitoring.md new file mode 100644 index 00000000..718abf6a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/monitoring.md @@ -0,0 +1,14 @@ +--- +title: 监控 +summary: 监控 +author: Guo Huan +date: 2022-04-29 +--- + +# 监控 + +因为逻辑复制是基于与物理流复制相似的架构的,一个发布节点上的监控也类似于对物理复制主节点的监控。 + +有关订阅的监控信息在pg_stat_subscription中可以看到。每一个订阅工作者在这个视图都有一行。一个订阅能有零个或者多个活跃订阅工作者取决于它的状态。 + +通常,对于一个已启用的订阅会有单一的应用进程运行。一个被禁用的订阅或者崩溃的订阅在这个视图中不会有行存在。如果有任何表的数据同步正在进行,对正在被同步的表会有额外的工作者。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/publication-subscription.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/publication-subscription.md new file mode 100644 index 00000000..049c73db --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/publication-subscription.md @@ -0,0 +1,20 @@ +--- +title: 发布订阅 +summary: 发布订阅 +author: Guo Huan +date: 2022-04-29 +--- + +# 发布订阅 + +发布和订阅基于逻辑复制实现,其中有一个或者更多订阅者订阅一个发布者节点上的一个或者更多发布。订阅者从它们所订阅的发布拉取数据。 + +发布者上的更改会被实时发送给订阅者。订阅者以与发布者相同的顺序应用那些数据,这样在一个订阅中能够保证发布的事务一致性。这种数据复制的方法有时候也被称为事务性复制。 + +发布订阅的典型用法是: + +- 在一个数据库或者一个数据库的子集中发生更改时,把增量的改变发送给订阅者。 +- 在更改到达订阅者时引发触发器。 +- 把多个数据库联合到单一数据库中(例如用于分析目的)。 + +订阅者数据库的行为与任何其他MogDB实例相同,并且可以被用作其他数据库的发布者,只需要定义它自己的发布。当订阅者被应用当作只读时,单一的订阅中不会有冲突。在另一方面,如果应用或者对相同表集合的订阅者执行了其他的写动作,冲突可能会发生。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/publications.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/publications.md new file mode 100644 index 00000000..a1a6e9d5 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/publications.md @@ -0,0 +1,22 @@ +--- +title: 发布 +summary: 发布 +author: Guo Huan +date: 2022-04-29 +--- + +# 发布 + +发布可以被定义在任何物理复制的主服务器上。定义有发布的节点被称为发布者。发布是从一个表或者一组表生成的改变的集合,也可以被描述为更改集合或者复制集合。每个发布都只存在于一个数据库中。 + +发布与模式不同,不会影响表的访问方式。如果需要,每个表都可以被加入到多个发布。当前,发布只能包含表。对象必须被明确地加入到发布,除非发布是用ALL TABLES创建的。 + +发布可以选择把它们产生的更改限制为INSERT、UPDATE、DELETE的任意组合,类似于触发器如何被特定事件类型触发的方式。默认情况下,所有操作类型都会被复制。 + +为了能够复制UPDATE和DELETE操作,被发布的表必须配置有一个“复制标识”,这样在订阅者那一端才能标识对于更新或删除合适的行。默认情况下,复制标识就是主键(如果有主键)。也可以在复制标识上设置另一个唯一索引(有特定的额外要求)。如果表没有合适的键,那么可以设置成复制标识“full”,它表示整个行都成为那个键。不过,这样做效率很低,只有在没有其他方案的情况下才应该使用。如果在发布者端设置了“full”之外的复制标识,在订阅者端也必须设置一个复制标识,它应该由相同的或者少一些的列组成。如何设置复制标识的细节请参考REPLICA IDENTITY。如果在复制UPDATE或DELETE操作的发布中加入了没有复制标识的表,那么订阅者上后续的UPDATE或DELETE操作将导致错误。不管有没有复制标识,INSERT操作都能继续下去。 + +每一个发布都可以有多个订阅者。 + +Publication通过使用CREATE PUBLICATION命令创建并且可以在之后使用相应的命令进行修改或者删除。 + +表可以使用ALTER PUBLICATION动态地增加或者移除。ADD TABLE以及DROP TABLE操作都是事务性的,因此一旦该事务提交,该表将以正确的快照开始或者停止复制。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/quick-setup.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/quick-setup.md new file mode 100644 index 00000000..b0dd9919 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/quick-setup.md @@ -0,0 +1,36 @@ +--- +title: 快速设置 +summary: 快速设置 +author: Guo Huan +date: 2022-04-29 +--- + +# 快速设置 + +首先在postgresql.conf中设置配置选项: + +```bash +wal_level = logical +``` + +对于一个基础设置来说,其他所需的设置使用默认值就足够了。 + +需要调整pg_hba.conf以允许复制(这里的值取决于实际的网络配置以及用于连接的用户): + +```bash +host all repuser 0.0.0.0/0 sha256 +``` + +然后在发布者数据库上: + +```sql +CREATE PUBLICATION mypub FOR TABLE users, departments; +``` + +并且在订阅者数据库上: + +```sql +CREATE SUBSCRIPTION mysub CONNECTION 'dbname=foo host=bar user=repuser' PUBLICATION mypub; +``` + +上面的语句将开始复制过程,复制对那些表的增量更改。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/restrictions.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/restrictions.md new file mode 100644 index 00000000..72e0247e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/restrictions.md @@ -0,0 +1,22 @@ +--- +title: 限制 +summary: 限制 +author: Guo Huan +date: 2022-04-29 +--- + +# 限制 + +发布订阅基于逻辑复制实现,继承所有逻辑复制的限制,同时发布订阅还有下列额外的限制或者缺失的功能。 + +数据库模式和DDL命令不会被复制。初始模式可以手工使用gs_dump --schema-only进行拷贝。后续的模式改变需要手工保持同步。 + +序列数据不被复制。后台由序列支撑的serial或者标识列中的数据当然将被作为表的一部分复制,但是序列本身在订阅者上仍将显示开始值。如果订阅者被用作一个只读数据库,那么这通常不会是什么问题。不过,如果订阅者数据库预期有某种转换或者容错,那么序列需要被更新到最后的值,要么通过从发布者拷贝当前数据的防范(也许使用gs_dump),要么从表本身决定一个足够高的值。 + +只有表支持复制,包括分区表。试图复制其他类型的关系,例如视图、物化视图或外部表,将会导致错误。 + +同一数据库内的多个订阅不应当订阅内容重复的发布(指发布相同的表),否则会产生数据重复或者主键冲突。 + +如果被发布的表中包含不支持btree/hash索引的数据类型(如地理类型等),那么该表需要有主键,才能成功的复制UPDATE/DELETE操作到订阅端。否则复制会失败,同时订阅端会出现“FATAL: could not identify an equality operator for type xx”的日志。 + +使用gs_probackup备份发布端时,由于gs_probackup工具本身不支持备份逻辑复制槽,所以备份恢复后,会由于逻辑复制槽不存在,而使得原有的发布订阅关系无法正常建立。建议使用gs_basebackup工具备份发布端。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/security.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/security.md new file mode 100644 index 00000000..1b76b527 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/security.md @@ -0,0 +1,20 @@ +--- +title: 安全性 +summary: 安全性 +author: Guo Huan +date: 2022-04-29 +--- + +# 安全性 + +用于复制连接的角色必须具有REPLICATION属性(或者是具有SYSADMIN权限用户)。如果角色缺少SUPERUSER和BYPASSRLS,发布者的行安全策略可以执行。角色的访问权限必须在pg_hba.conf中配置,并且必须具有LOGIN属性。 + +要创建发布,用户必须在数据库中有CREATE特权。 + +要把表加入到一个发布,用户必须在该表上有拥有权。要创建一个自动发布所有表的发布,用户必须是一个具有SYSADMIN权限用户。 + +要创建订阅,用户必须是一个具有SYSADMIN权限用户。 + +订阅的应用过程将在本地数据库上以具有SYSADMIN权限用户的特权运行。 + +特权检查仅在复制连接开始时被执行一次。在从发布者读到每一个更改记录时不会重新检查特权,在每一个更改被应用时也不会重新检查特权。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/subscriptions.md b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/subscriptions.md new file mode 100644 index 00000000..897822fb --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/logical-replication/publication-subscription/subscriptions.md @@ -0,0 +1,28 @@ +--- +title: 订阅 +summary: 订阅 +author: Guo Huan +date: 2022-04-29 +--- + +# 订阅 + +订阅是逻辑复制的下游端。订阅被定义在其中的节点被称为订阅者。一个订阅会定义到另一个数据库的连接以及它想要订阅的发布集合(一个或者多个)。 + +订阅者数据库的行为与任何其他MogDB实例相同,并且可以被用作其他数据库的发布者,只需要定义它自己的发布。 + +如果需要,一个订阅者节点可以有多个订阅。可以在一对发布者-订阅者之间定义多个订阅,在这种情况下要确保被订阅的发布对象不会重叠。 + +每一个订阅都将通过一个复制槽接收更改。预先存在的表的初始数据暂时不支持同步。 + +如果当前用户是一个具有SYSADMIN权限用户,则订阅会被gs_dump转储。否则订阅会被跳过并且写出一个警告,因为不具有SYSADMIN权限用户不能从pg_subscription目录中读取所有的订阅信息。 + +可以使用CREATE SUBSCRIPTION增加订阅,并且使用ALTER SUBSCRIPTION在任何时刻修改订阅,还可以使用DROP SUBSCRIPTION删除订阅。 + +在一个订阅被删除并且重建时,同步信息会丢失。这意味着数据必须被重新同步。 + +模式定义不会被复制,并且被发布的表必须在订阅者上存在。只有常规表可以成为复制的目标。例如,不能复制视图。 + +表在发布者和订阅者之间使用完全限定的表名进行匹配。不支持复制到订阅者上命名不同的表。 + +表的列也通过名称匹配。订阅表中的列顺序不需要与发布表中的顺序一样。列的数据类型也不需要一样,只要可以将数据的文本表示形式转换为目标类型即可。例如,您可以从integer类型的列复制到bigint类型的列。目标表还可以具有发布表中不存在的额外列。额外列都将使用目标表的定义中指定的默认值填充。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/1-materialized-view-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/1-materialized-view-overview.md new file mode 100644 index 00000000..fb816bf9 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/1-materialized-view-overview.md @@ -0,0 +1,12 @@ +--- +title: 物化视图概述 +summary: 物化视图概述 +author: Liuxu +date: 2021-05-21 +--- + +# 物化视图概述 + +物化视图是一种特殊的物理表,物化视图是相对普通视图而言的。普通视图是虚拟表,应用的局限性较大,任何对视图的查询实际上都是转换为对SQL语句的查询,性能并没有实际上提高。物化视图实际上就是存储SQL执行语句的结果,起到缓存的效果。 + +目前Ustore引擎不支持创建、使用物化视图。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/1-full-materialized-view-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/1-full-materialized-view-overview.md new file mode 100644 index 00000000..7d2a9590 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/1-full-materialized-view-overview.md @@ -0,0 +1,10 @@ +--- +title: 概述 +summary: 概述 +author: Liuxu +date: 2021-05-21 +--- + +# 概述 + +全量物化视图仅支持对已创建的物化视图进行全量更新,而不支持进行增量更新。创建全量物化视图语法和CREATE TABLE AS语法类似。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/2-full-materialized-view-usage.md b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/2-full-materialized-view-usage.md new file mode 100644 index 00000000..64ad2be1 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/2-full-materialized-view-usage.md @@ -0,0 +1,71 @@ +--- +title: 使用 +summary: 使用 +author: Liuxu +date: 2021-05-21 +--- + +# 使用 + +## 语法格式 + +- 创建全量物化视图 + + ```sql + CREATE MATERIALIZED VIEW [ view_name ] AS { query_block }; + ``` + +- 全量刷新物化视图 + + ```sql + REFRESH MATERIALIZED VIEW [ view_name ]; + ``` + +- 删除物化视图 + + ```sql + DROP MATERIALIZED VIEW [ view_name ]; + ``` + +- 查询物化视图 + + ```sql + SELECT * FROM [ view_name ]; + ``` + +## 示例 + +```sql +--准备数据。 +MogDB=# CREATE TABLE t1(c1 int, c2 int); +MogDB=# INSERT INTO t1 VALUES(1, 1); +MogDB=# INSERT INTO t1 VALUES(2, 2); + +--创建全量物化视图。 +MogDB=# CREATE MATERIALIZED VIEW mv AS select count(*) from t1; + +--查询物化视图结果。 +MogDB=# SELECT * FROM mv; + count +------- + 2 +(1 row) + +--向物化视图中基表插入数据。 +MogDB=# INSERT INTO t1 VALUES(3, 3); + +--对全量物化视图做全量刷新。 +MogDB=# REFRESH MATERIALIZED VIEW mv; +REFRESH MATERIALIZED VIEW + +--查询物化视图结果。 +MogDB=# SELECT * FROM mv; + count +------- + 3 +(1 row) + +--删除物化视图。 +MogDB=# DROP MATERIALIZED VIEW mv; +DROP MATERIALIZED VIEW +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/3-full-materialized-view-support-and-constraints.md b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/3-full-materialized-view-support-and-constraints.md new file mode 100644 index 00000000..7f554e8a --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/2-full-materialized-view/3-full-materialized-view-support-and-constraints.md @@ -0,0 +1,22 @@ +--- +title: 支持和约束 +summary: 支持和约束 +author: Liuxu +date: 2021-05-21 +--- + +# 支持和约束 + +## 支持场景 + +- 通常全量物化视图所支持的查询范围与CREATE TABLE AS语句一致。 +- 全量物化视图上支持创建索引。 +- 支持analyze、explain。 + +## 不支持场景 + +物化视图不支持增删改操作,只支持查询语句。 + +## 约束 + +全量物化视图的刷新、删除过程中会给基表加高级别锁,若物化视图的定义涉及多张表,需要注意业务逻辑,避免死锁产生。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/1-incremental-materialized-view-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/1-incremental-materialized-view-overview.md new file mode 100644 index 00000000..aad0be14 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/1-incremental-materialized-view-overview.md @@ -0,0 +1,10 @@ +--- +title: 概述 +summary: 概述 +author: Liuxu +date: 2021-05-21 +--- + +# 概述 + +增量物化视图可以对物化视图增量刷新,需要用户手动执行语句完成对物化视图在一段时间内的增量数据刷新。与全量创建物化视图的不同在于目前增量物化视图所支持场景较小。目前物化视图创建语句仅支持基表扫描语句或者UNION ALL语句。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/2-incremental-materialized-view-usage.md b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/2-incremental-materialized-view-usage.md new file mode 100644 index 00000000..ecd01b12 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/2-incremental-materialized-view-usage.md @@ -0,0 +1,92 @@ +--- +title: 使用 +summary: 使用 +author: Liuxu +date: 2021-05-21 +--- + +# 使用 + +## 语法格式 + +- 创建增量物化视图 + + ```sql + CREATE INCREMENTAL MATERIALIZED VIEW [ view_name ] AS { query_block }; + ``` + +- 全量刷新物化视图 + + ```sql + REFRESH MATERIALIZED VIEW [ view_name ]; + ``` + +- 增量刷新物化视图 + + ```sql + REFRESH INCREMENTAL MATERIALIZED VIEW [ view_name ]; + ``` + +- 删除物化视图 + + ```sql + DROP MATERIALIZED VIEW [ view_name ]; + ``` + +- 查询物化视图 + + ```sql + SELECT * FROM [ view_name ]; + ``` + +## 示例 + +```sql +--准备数据。 +MogDB=# CREATE TABLE t1(c1 int, c2 int); +MogDB=# INSERT INTO t1 VALUES(1, 1); +MogDB=# INSERT INTO t1 VALUES(2, 2); + +--创建增量物化视图。 +MogDB=# CREATE INCREMENTAL MATERIALIZED VIEW mv AS SELECT * FROM t1; +CREATE MATERIALIZED VIEW + +--插入数据。 +MogDB=# INSERT INTO t1 VALUES(3, 3); +INSERT 0 1 + +--增量刷新物化视图。 +MogDB=# REFRESH INCREMENTAL MATERIALIZED VIEW mv; +REFRESH MATERIALIZED VIEW + +--查询物化视图结果。 +MogDB=# SELECT * FROM mv; + c1 | c2 +----+---- + 1 | 1 + 2 | 2 + 3 | 3 +(3 rows) + +--插入数据。 +MogDB=# INSERT INTO t1 VALUES(4, 4); +INSERT 0 1 + +--全量刷新物化视图。 +MogDB=# REFRESH MATERIALIZED VIEW mv; +REFRESH MATERIALIZED VIEW + +--查询物化视图结果。 +MogDB=# select * from mv; + c1 | c2 +----+---- + 1 | 1 + 2 | 2 + 3 | 3 + 4 | 4 +(4 rows) + +--删除物化视图。 +MogDB=# DROP MATERIALIZED VIEW mv; +DROP MATERIALIZED VIEW +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/3-incremental-materialized-view-support-and-constraints.md b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/3-incremental-materialized-view-support-and-constraints.md new file mode 100644 index 00000000..1c232090 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/materialized-view/3-incremental-materialized-view/3-incremental-materialized-view-support-and-constraints.md @@ -0,0 +1,30 @@ +--- +title: 支持和约束 +summary: 支持和约束 +author: Liuxu +date: 2021-05-21 +--- + +# 支持和约束 + +## 支持场景 + +- 单表查询语句。 +- 多个单表查询的UNION ALL。 +- 物化视图上支持创建索引。 +- 物化视图支持Analyze操作。 + +## 不支持场景 + +- 物化视图中不支持多表Join连接计划以及subquery计划。 +- 除少部分ALTER操作外,不支持对物化视图中基表执行绝大多数DDL操作。 +- 物化视图不支持增删改操作,只支持查询语句。 +- 不支持用临时表/hashbucket/unlog/分区表创建物化视图。 +- 不支持物化视图嵌套创建(即物化视图上创建物化视图)。 +- 仅支持行存表,不支持列存表。 +- 不支持UNLOGGED类型的物化视图,不支持WITH语法。 + +## 约束 + +- 物化视图定义如果为UNION ALL,则其中每个子查询需使用不同的基表。 +- 增量物化视图的创建、全量刷新、删除过程中会给基表加高级别锁,若物化视图的定义为UNION ALL,需要注意业务逻辑,避免死锁产生。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/benefits-of-partition-pruning.md b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/benefits-of-partition-pruning.md new file mode 100644 index 00000000..cce8de48 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/benefits-of-partition-pruning.md @@ -0,0 +1,66 @@ +--- +title: 分区裁剪的好处 +summary: 分区裁剪的好处 +author: Guo Huan +date: 2022-06-14 +--- + +# 分区裁剪的好处 + +分区裁剪是分区表中常用的性能优化手段。在扫描分区表前,如果能通过检查分区约束条件与每个分区的定义,提前排除不需要扫描的分区,可以极大地提升扫描性能。在查询规划阶段,如果分区约束为确定的表达式,在查询规划阶段就可以根据分区约束表达式裁掉不需要扫描的分区,这种分区裁剪方式一般称为**静态分区裁剪**。静态裁剪从EXPLAIN VERBOSE输出就可以看出裁剪结果,如下所示。 + +explain verbose select * from prune_tt01 where a<8 ; + +```sql +MogDB=# drop table if exists prune_tt01; +DROP TABLE +MogDB=# CREATE TABLE prune_tt01(a int, b int) +PARTITION BY RANGE(a) +( + PARTITION prune_tt01_p1 VALUES LESS THAN(5), + PARTITION prune_tt01_p2 VALUES LESS THAN(10), + PARTITION prune_tt01_p3 VALUES LESS THAN(15), + PARTITION prune_tt01_p4 VALUES LESS THAN(MAXVALUE) +); +CREATE TABLE +MogDB=# INSERT INTO prune_tt01 VALUES (generate_series(1, 20), generate_series(1,20)); +INSERT 0 20 +MogDB=# CREATE INDEX index_prune_tt01 ON prune_tt01 USING btree(a) LOCAL; +CREATE INDEX +MogDB=# explain verbose select * from prune_tt01 where a<8 ; + QUERY PLAN +---------------------------------------------------------------------------------------------------- + Partition Iterator (cost=13.80..27.75 rows=716 width=8) + Output: a, b + Iterations: 2 + Selected Partitions: 1..2 + -> Partitioned Bitmap Heap Scan on public.prune_tt01 (cost=13.80..27.75 rows=716 width=8) + Output: a, b + Recheck Cond: (prune_tt01.a < 8) + -> Partitioned Bitmap Index Scan on index_prune_tt01 (cost=0.00..13.62 rows=716 width=0) + Index Cond: (prune_tt01.a < 8) +(9 rows) +``` + +但是在很多场景下,例如PREPARE-EXECUTE执行方式和分区约束表达式中包含子查询的场景在查询规划阶段,分区约束表达式是不确定的或包含未知的参数,查询规划阶段是不能裁剪的,只能在执行阶段,通过外部参数和子查询的结果确定分区表达式后进行裁剪,通常将在执行阶段做的裁剪称为**动态分区裁剪**。动态裁剪可以通过explain verbose从执行看到裁剪信息(Selected Partitions: PART)如下所示。 + +explain verbose select * from prune_tt01 where a < (select 8); + +```sql +MogDB=# explain verbose select * from prune_tt01 where a < (select 8); + QUERY PLAN +-------------------------------------------------------------------------------------- + Partition Iterator (cost=0.01..36.87 rows=716 width=8) + Output: prune_tt01.a, prune_tt01.b + Iterations: PART + Selected Partitions: PART + InitPlan 1 (returns $0) + -> Result (cost=0.00..0.01 rows=1 width=0) + Output: 8 + -> Partitioned Seq Scan on public.prune_tt01 (cost=0.00..36.86 rows=716 width=8) + Output: prune_tt01.a, prune_tt01.b + Filter: (prune_tt01.a < $0) +(10 rows) +``` + +MogDB自3.0版本后引入了分区表的动态裁剪,大大减少了从磁盘检索的数据量并缩短了处理时间,从而提高查询性能并优化资源利用率。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/dynamic-partition-pruning.md b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/dynamic-partition-pruning.md new file mode 100644 index 00000000..0d440c9d --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/dynamic-partition-pruning.md @@ -0,0 +1,260 @@ +--- +title: 动态分区裁剪 +summary: 动态分区裁剪 +author: Guo Huan +date: 2022-06-14 +--- + +# 动态分区裁剪 + +动态分区裁剪主要支持以下三种类型: + +1. Prepare-Execute(绑定变量)执行方式,分区裁剪表达式和静态裁剪类似,唯一区别是静态表达式一侧为Const,动态分区裁剪表达式一侧为外部参数或外部参数组成的表达式。例如: + + ```sql + prepare ps(int) as select * from prune_tt01 where a > $1; + explain verbose execute ps(12); + ``` + +2. 查询语句中包含子查询,主要分为对主查询中的分区表进行裁剪和子查询中的分区表进行裁剪两种方式: + + - 对主查询中的分区表进行裁剪,子查询一般为非相关子查询,子查询作为主查询分区裁剪表达式的一侧,另一侧为分区键,例如 + + ```sql + select * from prune_tt01 where a > (select a from t2 limit 1); + ``` + + - 对子查询中的分区表进行裁剪,子查询一般为相关子查询,且该子查询不支持提升。注意:相关子查询中涉及到对分区表多次裁剪,explain analyze显示的最后一次的裁剪结果。例如: + any子查询: + + ```sql + explain analyze select * from t2 where a > any(select a from prune_tt01 where prune_tt01.a = t2.a); + ``` + + exists子查询: + + ```sql + explain analyze select * from t2 where exists (select a from prune_tt01 where prune_tt01.a = t2.a limit 1); + ``` + +3. NestLoop参数化查询,即查询计划为NestLoop+indexscan查询方式,要求分区表的分区键为两个表的连接键,同时分区键上创建有索引。 + +以下为动态分区裁剪的案例。 + +```sql +drop table if exists prune_tt01; +CREATE TABLE prune_tt01(a int, b int) +PARTITION BY RANGE(a) +( + PARTITION prune_tt01_p1 VALUES LESS THAN(5), + PARTITION prune_tt01_p2 VALUES LESS THAN(10), + PARTITION prune_tt01_p3 VALUES LESS THAN(15), + PARTITION prune_tt01_p4 VALUES LESS THAN(MAXVALUE) +); +INSERT INTO prune_tt01 VALUES (generate_series(1, 20), generate_series(1,20)); +CREATE INDEX index_prune_tt01 ON prune_tt01 USING btree(a) LOCAL; + +drop table if exists tt02; +create table tt02(a int, b int); +INSERT INTO tt02 VALUES (generate_series(1, 20), generate_series(1,20)); +``` + +**prepare-execute(绑定变量)场景:** + +```sql +MogDB=# prepare ps(int) as select * from prune_tt01 where a > $1; +PREPARE +MogDB=# explain verbose execute ps(12); + QUERY PLAN +-------------------------------------------------------------------------------------- + Partition Iterator (cost=0.00..36.86 rows=716 width=8) + Output: a, b + Iterations: PART + Selected Partitions: PART + -> Partitioned Seq Scan on public.prune_tt01 (cost=0.00..36.86 rows=716 width=8) + Output: a, b + Filter: (prune_tt01.a > $1) +(7 rows) + +MogDB=# explain analyze execute ps(12); + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------- + Partition Iterator (cost=0.00..36.86 rows=716 width=8) (actual time=0.099..0.110 rows=8 loops=1) + Iterations: 2 + Selected Partitions: 3..4 + -> Partitioned Seq Scan on prune_tt01 (cost=0.00..36.86 rows=716 width=8) (actual time=0.031..0.034 rows=8 loops=2) + Filter: (a > $1) + Rows Removed by Filter: 3 + Total runtime: 0.218 ms +(7 rows) +``` + +**子查询场景:** + +- 对主查询中的分区表进行裁剪: + +```sql +MogDB=# explain verbose select * from prune_tt01 where a > (select a from t2 where a > 12 limit 1); + QUERY PLAN +-------------------------------------------------------------------------------------- + Partition Iterator (cost=0.04..36.90 rows=716 width=8) + Output: prune_tt01.a, prune_tt01.b + Iterations: PART + Selected Partitions: PART + InitPlan 1 (returns $0) + -> Limit (cost=0.00..0.04 rows=1 width=4) + Output: t2.a + -> Seq Scan on public.t2 (cost=0.00..1.75 rows=49 width=4) + Output: t2.a + Filter: (t2.a > 12) + -> Partitioned Seq Scan on public.prune_tt01 (cost=0.00..36.86 rows=716 width=8) + Output: prune_tt01.a, prune_tt01.b + Filter: (prune_tt01.a > $0) +(13 rows) + +MogDB=# explain analyze select * from prune_tt01 where a > (select a from t2 where a > 12 limit 1); + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------- + Partition Iterator (cost=0.04..36.90 rows=716 width=8) (actual time=0.172..0.180 rows=7 loops=1) + Iterations: 2 + Selected Partitions: 3..4 + InitPlan 1 (returns $0) + -> Limit (cost=0.00..0.04 rows=1 width=4) (actual time=0.093..0.093 rows=1 loops=1) + -> Seq Scan on t2 (cost=0.00..1.75 rows=49 width=4) (actual time=0.091..0.091 rows=1 loops=1) + Filter: (a > 12) + Rows Removed by Filter: 12 + -> Partitioned Seq Scan on prune_tt01 (cost=0.00..36.86 rows=716 width=8) (actual time=0.020..0.020 rows=7 loops=2) + Filter: (a > $0) + Rows Removed by Filter: 4 + Total runtime: 0.301 ms +(12 rows) +``` + +- 对子查询中的分区表进行裁剪: + + any子查询: + +```sql +MogDB=# explain verbose select * from t2 where a > any(select a from prune_tt01 where prune_tt01.a = t2.a); + QUERY PLAN +---------------------------------------------------------------------------------------------------------- + Seq Scan on public.t2 (cost=0.00..582.83 rows=30 width=8) + Output: t2.a, t2.b + Filter: (SubPlan 1) + SubPlan 1 + -> Partition Iterator (cost=4.34..15.01 rows=11 width=4) + Output: prune_tt01.a + Iterations: PART + Selected Partitions: PART + -> Partitioned Bitmap Heap Scan on public.prune_tt01 (cost=4.34..15.01 rows=11 width=4) + Output: prune_tt01.a + Recheck Cond: (prune_tt01.a = t2.a) + -> Partitioned Bitmap Index Scan on index_prune_tt01 (cost=0.00..4.33 rows=11 width=0) + Index Cond: (prune_tt01.a = t2.a) +(13 rows) + +MogDB=# explain analyze select * from t2 where a > any(select a from prune_tt01 where prune_tt01.a = t2.a); + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------------------------------------ + Seq Scan on t2 (cost=0.00..582.83 rows=30 width=8) (actual time=2.130..2.130 rows=0 loops=1) + Filter: (SubPlan 1) + Rows Removed by Filter: 60 + SubPlan 1 + -> Partition Iterator (cost=4.34..15.01 rows=11 width=4) (actual time=1.860..1.877 rows=20 loops=60) + Iterations: 1 + Selected Partitions: 4 + -> Partitioned Bitmap Heap Scan on prune_tt01 (cost=4.34..15.01 rows=11 width=4) (actual time=0.566..0.576 rows=20 loops=60) + Recheck Cond: (a = t2.a) + Heap Blocks: exact=20 + -> Partitioned Bitmap Index Scan on index_prune_tt01 (cost=0.00..4.33 rows=11 width=0) (actual time=0.482..0.482 rows=20 loops=60) + Index Cond: (a = t2.a) + Total runtime: 2.600 ms +(13 rows) +``` + + exists子查询: + +```sql +MogDB=# explain verbose select * from t2 where exists (select a from prune_tt01 where prune_tt01.a = t2.a limit 1); + QUERY PLAN +---------------------------------------------------------------------------------------------------------------- + Seq Scan on public.t2 (cost=0.00..319.92 rows=30 width=8) + Output: t2.a, t2.b + Filter: (SubPlan 1) + SubPlan 1 + -> Limit (cost=4.34..5.31 rows=1 width=4) + Output: prune_tt01.a + -> Partition Iterator (cost=4.34..15.01 rows=11 width=4) + Output: prune_tt01.a + Iterations: PART + Selected Partitions: PART + -> Partitioned Bitmap Heap Scan on public.prune_tt01 (cost=4.34..15.01 rows=11 width=4) + Output: prune_tt01.a + Recheck Cond: (prune_tt01.a = t2.a) + -> Partitioned Bitmap Index Scan on index_prune_tt01 (cost=0.00..4.33 rows=11 width=0) + Index Cond: (prune_tt01.a = t2.a) +(15 rows) + +MogDB=# explain analyze select * from t2 where exists (select a from prune_tt01 where prune_tt01.a = t2.a limit 1); + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------------------------------------------ + Seq Scan on t2 (cost=0.00..319.92 rows=30 width=8) (actual time=0.058..0.875 rows=20 loops=1) + Filter: (SubPlan 1) + Rows Removed by Filter: 40 + SubPlan 1 + -> Limit (cost=4.34..5.31 rows=1 width=4) (actual time=0.826..0.826 rows=20 loops=60) + -> Partition Iterator (cost=4.34..15.01 rows=11 width=4) (actual time=0.789..0.789 rows=20 loops=60) + Iterations: 1 + Selected Partitions: 4 + -> Partitioned Bitmap Heap Scan on prune_tt01 (cost=4.34..15.01 rows=11 width=4) (actual time=0.162..0.162 rows=20 loops=60) + Recheck Cond: (a = t2.a) + Heap Blocks: exact=20 + -> Partitioned Bitmap Index Scan on index_prune_tt01 (cost=0.00..4.33 rows=11 width=0) (actual time=0.123..0.123 rows=20 loops=60) + Index Cond: (a = t2.a) + Total runtime: 1.151 ms +(14 rows) +``` + +**nestloop场景:** + +以下参数设置仅为了模拟SQL语句使用nestloop(通常情况下优化器会根据表的数据量选择最优的访问路径) + +```sql +MogDB=# SET enable_material = OFF; +SET +MogDB=# SET enable_mergejoin = OFF; +SET +MogDB=# SET enable_hashjoin = OFF; +SET +``` + +```sql +MogDB=# explain verbose select * from prune_tt01 inner join tt02 on prune_tt01.a = tt02.a; + QUERY PLAN +------------------------------------------------------------------------------------------------------------------- + Nested Loop (cost=0.00..1501.91 rows=23091 width=16) + Output: prune_tt01.a, prune_tt01.b, tt02.a, tt02.b + -> Seq Scan on public.tt02 (cost=0.00..31.49 rows=2149 width=8) + Output: tt02.a, tt02.b + -> Partition Iterator (cost=0.00..0.57 rows=11 width=8) + Output: prune_tt01.a, prune_tt01.b + Iterations: PART + Selected Partitions: PART + -> Partitioned Index Scan using index_prune_tt01 on public.prune_tt01 (cost=0.00..0.57 rows=11 width=8) + Output: prune_tt01.a, prune_tt01.b + Index Cond: (prune_tt01.a = tt02.a) +(11 rows) + +MogDB=# explain analyze select * from prune_tt01 inner join tt02 on prune_tt01.a = tt02.a; + QUERY PLAN +-------------------------------------------------------------------------------------------------------------------------------------------------------- + Nested Loop (cost=0.00..1501.91 rows=23091 width=16) (actual time=0.078..0.535 rows=20 loops=1) + -> Seq Scan on tt02 (cost=0.00..31.49 rows=2149 width=8) (actual time=0.023..0.030 rows=20 loops=1) + -> Partition Iterator (cost=0.00..0.57 rows=11 width=8) (actual time=0.441..0.462 rows=20 loops=20) + Iterations: 1 + Selected Partitions: 4 + -> Partitioned Index Scan using index_prune_tt01 on prune_tt01 (cost=0.00..0.57 rows=11 width=8) (actual time=0.146..0.158 rows=20 loops=20) + Index Cond: (a = tt02.a) + Total runtime: 0.770 ms +(8 rows) +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/how-to-identify-whether-partition-pruning-has-been-used.md b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/how-to-identify-whether-partition-pruning-has-been-used.md new file mode 100644 index 00000000..1074d292 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/how-to-identify-whether-partition-pruning-has-been-used.md @@ -0,0 +1,12 @@ +--- +title: 如何确定是否使用了分区裁剪 +summary: 如何确定是否使用了分区裁剪 +author: Guo Huan +date: 2022-06-22 +--- + +### 如何确定是否使用了分区裁剪 + +MogDB是否使用分区裁剪会反映在语句的执行计划中,可以通过EXPLAIN VERBOSE或EXPLAIN ANALYZE语句查看。 + +分区裁剪信息反映在执行计划列Iterations和Selected Partitions中。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/information-that-can-be-used-for-partition-pruning.md b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/information-that-can-be-used-for-partition-pruning.md new file mode 100644 index 00000000..88f5bc96 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/information-that-can-be-used-for-partition-pruning.md @@ -0,0 +1,33 @@ +--- +title: 可用于分区裁剪的信息 +summary: 可用于分区裁剪的信息 +author: Guo Huan +date: 2022-06-14 +--- + +# 可用于分区裁剪的信息 + +可以对分区列执行分区裁剪。 + +当您在范围或列表分区列上使用范围、`LIKE`、等式和`IN`列表谓词,以及在哈希分区列上使用等式和`IN`列表谓词时,MogDB会裁剪分区。 + +例如示例1中,表prune_tt01在列a上按范围分区。 + +MogDB使用分区列上的谓词来执行分区裁剪,如下所示。 + +**示例1 创建带有分区裁剪的表** + +```sql +CREATE TABLE prune_tt01(a int, b int) +PARTITION BY RANGE(a) +( + PARTITION prune_tt01_p1 VALUES LESS THAN(5), + PARTITION prune_tt01_p2 VALUES LESS THAN(10), + PARTITION prune_tt01_p3 VALUES LESS THAN(15), + PARTITION prune_tt01_p4 VALUES LESS THAN(MAXVALUE) +); +INSERT INTO prune_tt01 VALUES (generate_series(1, 20), generate_series(1,20)); +CREATE INDEX index_prune_tt01 ON prune_tt01 USING btree(a) LOCAL; + +select * from prune_tt01 where a > 8 ; +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/static-partition-pruning.md b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/static-partition-pruning.md new file mode 100644 index 00000000..51eb872e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/partition-pruning/static-partition-pruning.md @@ -0,0 +1,60 @@ +--- +title: 静态分区裁剪 +summary: 静态分区裁剪 +author: Guo Huan +date: 2022-06-14 +--- + +# 静态分区裁剪 + +MogDB主要根据静态谓词确定何时使用静态裁剪。 + +如果在解析时MogDB可以识别访问了哪个连续的分区集合,则执行计划中的**Selected Partitions:**列显示正在访问的分区的开始值和结束值。对于任何其他分区裁剪情况(包括动态裁剪),MogDB都会显示**Selected Partitions:**。 + +静态分区裁剪可通过[EXPLAIN VERBOSE](../../../reference-guide/sql-syntax/EXPLAIN.md)语句查看执行计划。如下示例查询中,prune_tt01表有四个分区,查询计划中显示SeqScan支持扫描的分区为3和4,从而确定分区1和2已经在查询计划中裁剪掉。 + +```sql +MogDB=# \d+ prune_tt01 + Table "public.prune_tt01" + Column | Type | Modifiers | Storage | Stats target | Description +--------+---------+-----------+---------+--------------+------------- + a | integer | | plain | | + b | integer | | plain | | +Indexes: + "index_prune_tt01" btree (a) LOCAL TABLESPACE pg_default +Partition By RANGE(a) +Number of partitions: 4 (View pg_partition to check each partition range.) +Has OIDs: no +Options: orientation=row, compression=no +``` + +```sql +MogDB=# explain verbose select * from prune_tt01 where a>12; + QUERY PLAN +---------------------------------------------------------------------------------------------------- + Partition Iterator (cost=13.80..27.75 rows=716 width=8) + Output: a, b + Iterations: 2 + Selected Partitions: 3..4 + -> Partitioned Bitmap Heap Scan on public.prune_tt01 (cost=13.80..27.75 rows=716 width=8) + Output: a, b + Recheck Cond: (prune_tt01.a > 12) + -> Partitioned Bitmap Index Scan on index_prune_tt01 (cost=0.00..13.62 rows=716 width=0) + Index Cond: (prune_tt01.a > 12) +(9 rows) +``` + +
+ +静态分区裁剪的详细支持范围如下表所示。 + +**表1** 静态分区裁剪的详细支持范围 + +| 序号 | 约束名称 | 约束范围 | +| ---- | ---------------- | ------------------------------------------------------------ | +| 1 | 分区表类型 | Range分区、List分区、Hash分区 | +| 2 | 分区表达式类型 | - 分区约束为单个表达式,如`a >12;`
- 分区约束为BOOL表达式,如`a > 2 and a < 12;`
- 分区约束为数组,如`a in (2, 3);`
- 分区约束为常量表达式,如`1 = 1;`
- 分区约束为`Is (NOT)NULL`表达式,如`a IS NULL` | +| 3 | 分区表达式操作符 | - Range分区表支持:`=`、`>`、`>=`、`<`、`<=`五种操作符
- List分区和Hash分区只支持`=`操作符 | +| 4 | 分区表达式参数 | 一侧为分区键,另一侧为常量,例如:`a > 12` | +| 5 | 二级分区 | Range、List和Hash三种分区表的组合,例如:Range-List等等 | +| 6 | 分区裁剪结果显示 | Explain verbose显示裁剪分区链表 | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-hash-partitioning.md b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-hash-partitioning.md new file mode 100644 index 00000000..36c6d60b --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-hash-partitioning.md @@ -0,0 +1,41 @@ +--- +title: 何时使用哈希分区 +summary: 何时使用哈希分区 +author: Guo Huan +date: 2022-06-14 +--- + +# 何时使用哈希分区 + +哈希分区对于基于哈希算法在分区之间随机分布数据,而不是对相似数据进行分组很有用。 + +在有些情况下,虽然可以确定分区关键字,但分区数据应该位于哪个分区并不明显。有些情况则不希望像范围分区那样对相似数据进行分组,而是希望数据的分布与其业务或逻辑视图不一致。哈希分区根据将关键字传递给哈希算法的结果,将某一行放入某个分区中。 + +使用这种方法,数据在分区中随机分布而非分组。这对于某些数据来说是一种很好的方法,但可能不适用于管理历史数据。然而,哈希分区与范围分区具有一些相同的性能特征。例如,分区裁剪仅限于等式谓词。您还可以使用分区连接、并行索引访问和并行DML。 + +哈希分区的优点是,数据的分布几乎是随机的,所以分布相对均匀,能够在一定程度上避免热点问题。 + +哈希分区的缺点是: + +- 在不额外存储数据的情况下,无法执行范围查询。 +- 在添加或删除节点时,由于每个节点都需要一个相应的哈希值,所以增加节点需要修改哈希函数,这会导致许多现有的数据都要重新映射,引起数据大规模移动。并且在此期间,系统可能无法继续工作。 + +示例1使用列`s_productid`作为分区关键字为表`sales_hash`创建了四个哈希分区。与products表的并行连接可以利用部分或完全分区连接。此时分区裁剪有利于仅访问单个产品或一部分产品的销售数据的查询。 + +如果您没有明确指定分区名称,而是指定哈希分区的编号,那么MogDB会自动为分区生成内部名称。 + +**示例1 创建具有哈希分区的表** + +```sql +CREATE TABLE sales_hash + (s_productid NUMBER, + s_saledate DATE, + s_custid NUMBER, + s_totalprice NUMBER) +PARTITION BY HASH(s_productid) +( PARTITION p1 , + PARTITION p2, + PARTITION p3 , + PARTITION p4 +); +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-list-partitioning.md b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-list-partitioning.md new file mode 100644 index 00000000..dc2cc118 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-list-partitioning.md @@ -0,0 +1,33 @@ +--- +title: 何时使用列表分区 +summary: 何时使用列表分区 +author: Guo Huan +date: 2022-06-14 +--- + +# 何时使用列表分区 + +列表分区可基于离散值将行显式映射到分区。 + +在示例1中,按区域分析帐户的客户经理可有效利用分区裁剪。 + +**示例1 创建具有列表分区的表** + +```sql +CREATE TABLE accounts +( id NUMBER +, account_number NUMBER +, customer_id NUMBER +, branch_id NUMBER +, region VARCHAR(2) +, status VARCHAR2(1) +) +PARTITION BY LIST (region) +( PARTITION p_northwest VALUES ('OR', 'WA') +, PARTITION p_southwest VALUES ('AZ', 'UT', 'NM') +, PARTITION p_northeast VALUES ('NY', 'VM', 'NJ') +, PARTITION p_southeast VALUES ('FL', 'GA') +, PARTITION p_northcentral VALUES ('SD', 'WI') +, PARTITION p_southcentral VALUES ('OK', 'TX') +); +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-range-partitioning.md b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-range-partitioning.md new file mode 100644 index 00000000..731db006 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/partition-management/recommendations-for-choosing-a-partitioning-strategy/when-to-use-range-partitioning.md @@ -0,0 +1,36 @@ +--- +title: 何时使用范围分区 +summary: 何时使用范围分区 +author: Guo Huan +date: 2022-06-14 +--- + +# 何时使用范围分区 + +范围分区在组织类似的数据时很有用,尤其是日期和时间数据。 + +范围分区是一种方便的历史数据分区方法。范围分区的边界定义了表或索引中分区的顺序。 + +大多数访问范围分区的SQL语句都关注时间范围。例如类似于“从特定时间段选择数据”的SQL语句。如果每个分区代表一个月内的数据,扫描的数据量减少为总数据的一小部分,这种优化方法称为**分区裁剪**。 + +当您需要定期加载新数据并清除旧数据时,范围分区也很有用,因为范围分区很容易添加或删除。例如,系统通常会保留一个滚动的数据窗口,将过去36个月的数据保持为在线状态。范围分区简化了这个过程。 + +总之,在以下情况下您可以考虑使用范围分区: + +- 经常需要对大型表中容易分区的列进行范围谓词扫描。 +- 希望维护一个滚动的数据窗口。 +- 无法在指定时间范围内对大型表完成管理操作,例如备份和还原,但可以根据分区范围列将其分成更小的逻辑块。 + +**示例1 创建具有范围分区的表** + +```sql +CREATE TABLE employees ( + id INT NOT NULL, + fname VARCHAR(30), + lname VARCHAR(30), + hired DATE NOT NULL DEFAULT '1970-01-01', + separated DATE DEFAULT '9999-12-31', + job_code INT, + store_id INT NOT NULL +); +``` \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-1-plpgsql-overview.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-1-plpgsql-overview.md new file mode 100644 index 00000000..92754416 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-1-plpgsql-overview.md @@ -0,0 +1,24 @@ +--- +title: PL/pgSQL语言函数介绍 +summary: PL/pgSQL语言函数介绍 +author: Guo Huan +date: 2021-11-10 +--- + +# PL/pgSQL语言函数介绍 + +PL/pgSQL是一种可载入的过程语言。 + +用PL/pgSQL创建的函数可以被用在任何可以使用内建函数的地方。例如,可以创建复杂条件的计算函数并且后面用它们来定义操作符或把它们用于索引表达式。 + +SQL被大多数数据库用作查询语言。它是可移植的并且容易学习。但是每一个SQL语句必须由数据库服务器单独执行。 + +这意味着客户端应用必须发送每一个查询到数据库服务器、等待它被处理、接收并处理结果、做一些计算,然后发送更多查询给服务器。如果客户端和数据库服务器不在同一台机器上,则会引起进程间通信并且将带来网络负担。 + +通过PL/pgSQL,可以将一整块计算和一系列查询分组在数据库服务器内部,这样就有了一种过程语言的能力并且使SQL更易用,同时能节省客户端/服务器通信开销。 + +- 客户端和服务器之间的额外往返通信被消除。 +- 客户端不需要的中间结果不必被整理或者在服务器和客户端之间传送。 +- 多轮的查询解析可以被避免。 + +PL/pgSQL可以使用SQL中所有的数据类型、操作符和函数。一些常见函数,例如gs_extend_library。 \ No newline at end of file diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-10-other-statements.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-10-other-statements.md new file mode 100644 index 00000000..2911f0c0 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-10-other-statements.md @@ -0,0 +1,20 @@ +--- +title: 其他语句 +summary: 其他语句 +author: Guo Huan +date: 2021-03-04 +--- + +# 其他语句 + +## 锁操作 + +MogDB提供了多种锁模式用于控制对表中数据的并发访问。这些模式可以用在MVCC(多版本并发控制)无法给出期望行为的场合。同样,大多数MogDB命令自动施加恰当的锁,以保证被引用的表在命令的执行过程中不会以一种不兼容的方式被删除或者修改。比如,在存在其他并发操作的时候,ALTER TABLE是不能在同一个表上执行的。 + +## 游标操作 + +MogDB中游标(cursor)是系统为用户开设的一个数据缓冲区,存放着SQL语句的执行结果。每个游标区都有一个名称。用户可以用SQL语句逐一从游标中获取记录,并赋给主变量,交由主语言进一步处理。 + +游标的操作主要有游标的定义、打开、获取和关闭。 + +完整的游标操作示例可参考[显式游标](1-11-cursors.md#显式游标)。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-11-cursors.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-11-cursors.md new file mode 100644 index 00000000..159c1dfe --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-11-cursors.md @@ -0,0 +1,183 @@ +--- +title: 游标 +summary: 游标 +author: Guo Huan +date: 2021-03-04 +--- + +# 游标 + +## 游标概述 + +为了处理SQL语句,存储过程进程分配一段内存区域来保存上下文联系。游标是指向上下文区域的句柄或指针。借助游标,存储过程可以控制上下文区域的变化。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif)**须知**: +> +> 当游标作为存储过程的返回值时,如果使用JDBC调用该存储过程,返回的游标将不可用。 + +游标的使用分为显式游标和隐式游标。对于不同的SQL语句,游标的使用情况不同,详细信息请参见[表1](#游标使用情况)。 + +**表 1** 游标使用情况 + +| SQL语句 | 游标 | +| :------------------- | :------------- | +| 非查询语句 | 隐式的 | +| 结果是单行的查询语句 | 隐式的或显式的 | +| 结果是多行的查询语句 | 显式的 | + +## 显式游标 + +显式游标主要用于对查询语句的处理,尤其是在查询结果为多条记录的情况下。 + +**处理步骤** + +显式游标处理需六个PL/SQL步骤: + +1. **定义静态游标**:就是定义一个游标名,以及与其相对应的SELECT语句。 + + 定义静态游标的语法图,请参见[图1](#static_cursor_define)。 + + **图 1** static_cursor_define::= + + ![static_cursor_define](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/cursors-1.jpg) + + 参数说明: + + - cursor_name:定义的游标名。 + + - parameter:游标参数,只能为输入参数,其格式为: + + ```sql + parameter_name datatype + ``` + + - select_statement:查询语句。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明**: + > + > 根据执行计划的不同,系统会自动判断该游标是否可以用于以倒序的方式检索数据行。 + + **定义动态游标:**指ref游标,可以通过一组静态的SQL语句动态的打开游标。首先定义ref游标类型,然后定义该游标类型的游标变量,在打开游标时通过OPEN FOR动态绑定SELECT语句。 + + 定义动态游标的语法图,请参见[图2](#cursor_typename)和[图3](#dynamic_cursor_define)。 + + **图 2** cursor_typename::= + + ![cursor_typename](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/cursors-2.png) + + **图 3** dynamic_cursor_define::= + + ![dynamic_cursor_define](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/cursors-3.png) + +2. **打开静态游标:**就是执行游标所对应的SELECT语句,将其查询结果放入工作区,并且指针指向工作区的首部,标识游标结果集合。如果游标查询语句中带有FOR UPDATE选项,OPEN语句还将锁定数据库表中游标结果集合对应的数据行。 + + 打开静态游标的语法图,请参见[图4](#open_static_cursor)。 + + **图 4** open_static_cursor::= + + ![open_static_cursor](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/cursors-4.png) + + **打开动态游标:**可以通过OPEN FOR语句打开动态游标,动态绑定SQL语句。 + + 打开动态游标的语法图,请参见[图5](#open_dynamic_cursor)。 + + **图 5** open_dynamic_cursor::= + + ![open_dynamic_cursor](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/cursors-5.png) + + PL/SQL程序不能用OPEN语句重复打开一个游标。 + +3. 提取游标数据:检索结果集合中的数据行,放入指定的输出变量中。 + + 提取游标数据的语法图,请参见[图6](#fetch_cursor)。 + + **图 6** fetch_cursor::= + + ![fetch_cursor](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/cursors-6.png) + +4. 对该记录进行处理。 + +5. 继续处理,直到活动集合中没有记录。 + +6. 关闭游标:当提取和处理完游标结果集合数据后,应及时关闭游标,以释放该游标所占用的系统资源,并使该游标的工作区变成无效,不能再使用FETCH语句获取其中数据。关闭后的游标可以使用OPEN语句重新打开。 + + 关闭游标的语法图,请参见[图7](#close_cursor)。 + + **图 7** close_cursor::= + + ![close_cursor](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/cursors-7.jpg) + +**属性** + +游标的属性用于控制程序流程或者了解程序的状态。当运行DML语句时,PL/SQL打开一个内建游标并处理结果,游标是维护查询结果的内存中的一个区域,游标在运行DML语句时打开,完成后关闭。显式游标的属性为: + +- %FOUND布尔型属性:当最近一次读记录时成功返回,则值为TRUE。 +- %NOTFOUND布尔型属性:与%FOUND相反。 +- %ISOPEN布尔型属性:当游标已打开时返回TRUE。 +- %ROWCOUNT数值型属性:返回已从游标中读取的记录数。 + +## 隐式游标 + +对于非查询语句,如修改、删除操作,则由系统自动地为这些操作设置游标并创建其工作区,这些由系统隐含创建的游标称为隐式游标,隐式游标的名称为SQL,这是由系统定义的。 + +**简介** + +对于隐式游标的操作,如定义、打开、取值及关闭操作,都由系统自动地完成,无需用户进行处理。用户只能通过隐式游标的相关属性,来完成相应的操作。在隐式游标的工作区中,所存放的数据是最新处理的一条SQL语句所包含的数据,与用户自定义的显式游标无关。 + +**格式调用为**: SQL% + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明**: +> +> - INSERT、UPDATE、DELETE、SELECT语句中不必明确定义游标。 +> - 兼容O模式下,GUC参数behavior_compat_options为compat_cursor时,隐式游标跨存储过程有效。 + +**属性** + +隐式游标属性为: + +- SQL%FOUND布尔型属性:当最近一次读记录时成功返回,则值为TRUE。 +- SQL%NOTFOUND布尔型属性:与%FOUND相反。 +- SQL%ROWCOUNT数值型属性:返回已从游标中读取得记录数。 +- SQL%ISOPEN布尔型属性:取值总是FALSE。SQL语句执行完毕立即关闭隐式游标。 + +**示例** + +```sql +--删除员工表hr.staffs表中某部门的所有员工,如果该部门中已没有员工,则在部门表hr.sections中删除该部门。 + +CREATE OR REPLACE PROCEDURE proc_cursor3() +AS + DECLARE + V_DEPTNO NUMBER(4) := 100; + BEGIN + DELETE FROM hr.staffs WHERE section_ID = V_DEPTNO; + --根据游标状态做进一步处理 + IF SQL%NOTFOUND THEN + DELETE FROM hr.sections WHERE section_ID = V_DEPTNO; + END IF; + END; +/ + +CALL proc_cursor3(); + +--删除存储过程和临时表 +DROP PROCEDURE proc_cursor3; +``` + +## 游标循环 + +游标在WHILE语句、LOOP语句中的使用称为游标循环,一般这种循环都需要使用OPEN、FETCH和CLOSE语句。下面要介绍的一种循环不需要这些操作,可以简化游标循环的操作,这种循环方式适用于静态游标的循环,不用执行静态游标的四个步骤。 + +**语法** + +FOR AS循环的语法请参见[图8](#FOR_AS_loop)。 + +**图 8** FOR_AS_loop::= + + ![FOR_AS_loop](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/cursors-8.png) + +**注意事项** + +- 不能在该循环语句中对查询的表进行更新操作。 +- 变量loop_name会自动定义且只在此循环中有效,类型和select_statement的查询结果类型一致。loop_name的取值就是select_statement的查询结果。 +- 游标的属性中%FOUND、%NOTFOUND、%ROWCOUNT在MogDB数据库中都是访问同一个内部变量,事务和匿名块不支持多个游标同时访问。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-12-retry-management.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-12-retry-management.md new file mode 100644 index 00000000..02db7fa8 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-12-retry-management.md @@ -0,0 +1,26 @@ +--- +title: Retry管理 +summary: Retry管理 +author: Guo Huan +date: 2021-03-04 +--- + +# Retry管理 + +Retry是数据库在SQL或存储过程(包含匿名块)执行失败时,在数据库内部进行重新执行的过程,以提高执行成功率和用户体验。数据库内部通过检查发生错误时的错误码及Retry相关配置,决定是否进行重试。 + +- 失败时回滚之前执行的语句,并重新执行存储过程进行Retry。 + + 示例: + + ```sql + MogDB=# CREATE OR REPLACE PROCEDURE retry_basic ( IN x INT) + AS + BEGIN + INSERT INTO t1 (a) VALUES (x); + INSERT INTO t1 (a) VALUES (x+1); + END; + / + + MogDB=# CALL retry_basic(1); + ``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-13-debugging.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-13-debugging.md new file mode 100644 index 00000000..8ce94244 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-13-debugging.md @@ -0,0 +1,174 @@ +--- +title: 调试 +summary: 调试 +author: Guo Huan +date: 2021-03-04 +--- + +# 调试 + +## 语法 + +### RAISE语法 + +有以下五种语法格式: + +**图 1** raise_format::= + +![raise_format](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/debugging-1.png) + +**图 2** raise_condition::= + +![raise_condition](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/debugging-2.png) + +**图 3** raise_sqlstate::= + +![raise_sqlstate](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/debugging-3.png) + +**图 4** raise_option::= + +![raise_option](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/debugging-4.png) + +**图 5** raise::= + +![raise](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/debugging-5.png) + +**参数说明:** + +- level选项用于指定错误级别,有DEBUG,LOG,INFO,NOTICE,WARNING以及EXCEPTION(默认值)。EXCEPTION抛出一个正常终止当前事务的异常,其他的仅产生不同异常级别的信息。特殊级别的错误信息是否报告到客户端、写到服务器日志由[log_min_messages](../../reference-guide/guc-parameters/10-error-reporting-and-logging/2-logging-time.md#log_min_messages)和[client_min_messages](../../reference-guide/guc-parameters/10-error-reporting-and-logging/2-logging-time.md#client_min_messages)这两个配置参数控制。 + +- format:格式字符串,指定要报告的错误消息文本。格式字符串后可跟表达式,用于向消息文本中插入。在格式字符串中,%由format后面跟着的参数的值替换,%%用于打印出%。例如: + + ``` + --v_job_id 将替换字符串中的 %: + RAISE NOTICE 'Calling cs_create_job(%)',v_job_id; + ``` + +- option = expression:向错误报告中添加另外的信息。关键字option可以是MESSAGE、DETAIL、HINT以及ERRCODE,并且每一个expression可以是任意的字符串。 + + - MESSAGE,指定错误消息文本,这个选项不能用于在USING前包含一个格式字符串的RAISE语句中。 + - DETAIL,说明错误的详细信息。 + - HINT,用于打印出提示信息。 + - ERRCODE,向报告中指定错误码(SQLSTATE)。可以使用条件名称或者直接用五位字符的SQLSTATE错误码。 + +- condition_name:错误码对应的条件名。 + +- sqlstate:错误码。 + +如果在RAISE EXCEPTION命令中既没有指定条件名也没有指定SQLSTATE,默认用RAISE EXCEPTION (P0001)。如果没有指定消息文本,默认用条件名或者SQLSTATE作为消息文本。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif)**须知**: +> +> - 当由SQLSTATE指定了错误码,则不局限于已定义的错误码,可以选择任意包含五个数字或者大写的ASCII字母的错误码,而不是00000。建议避免使用以三个0结尾的错误码,因为这种错误码是类别码,会被整个种类捕获。 +> - 兼容O模式下,SQLCODE等于SQLSTATE。 +> +> ![https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明**: +> +> [图5](#raise::=)所示的语法不接任何参数。这种形式仅用于一个BEGIN块中的EXCEPTION语句,它使得错误重新被处理。 + +### EXCEPTION_INIT语法 + +兼容O模式下,支持使用EXCEPTION_INIT语法自定义错误码SQLCODE。语法格式如下: + +**图 6** exception_init::= + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/debugging-6.png) + +**参数说明:** + +- exception_name为用户申明的异常名,EXCEPTION_INIT语法必须出现在与申明异常相同部分,位于申明异常之后。 +- sqlcode为自定义的SQLCODE,必须为负整数,取值范围-2147483647~-1。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: 使用EXCEPTION_INIT语法自定义错误码SQLCODE时,SQLSTATE与SQLCODE相同,SQLERRM格式为” xxx: non-MogDB Exception”。比如自定义SQLCODE=-1,则SQLSTATE=“-1”,SQLERRM=” 1: non-MogDB Exception”。 + +## **示例** + +终止事务时,给出错误和提示信息: + +```sql +CREATE OR REPLACE PROCEDURE proc_raise1(user_id in integer) +AS +BEGIN +RAISE EXCEPTION 'Noexistence ID --> %',user_id USING HINT = 'Please check your user ID'; +END; +/ + +call proc_raise1(300011); + +--执行结果 +ERROR: Noexistence ID --> 300011 +HINT: Please check your user ID +``` + +两种设置SQLSTATE的方式: + +```sql +CREATE OR REPLACE PROCEDURE proc_raise2(user_id in integer) +AS +BEGIN +RAISE 'Duplicate user ID: %',user_id USING ERRCODE = 'unique_violation'; +END; +/ + +\set VERBOSITY verbose +call proc_raise2(300011); + +--执行结果 +ERROR: Duplicate user ID: 300011 +SQLSTATE: 23505 +``` + +如果主要的参数是条件名或者是SQLSTATE,可以使用: + +RAISE division_by_zero; + +RAISE SQLSTATE '22012'; + +例如: + +```sql +CREATE OR REPLACE PROCEDURE division(div in integer, dividend in integer) +AS +DECLARE +res int; + BEGIN + IF dividend=0 THEN + RAISE division_by_zero; + RETURN; + ELSE + res := div/dividend; + RAISE INFO 'division result: %', res; + RETURN; + END IF; + END; +/ +call division(3,0); + +--执行结果 +ERROR: division_by_zero +``` + +或者另一种方式: + +```sql +RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id; +``` + +兼容O模式下,支持使用语法EXCEPTION_INIT自定义错误码SQLCODE: + +```sql +declare + deadlock_detected exception; + pragma exception_init(deadlock_detected, -1); +begin + if 1 > 0 then + raise deadlock_detected; + end if; +exception + when deadlock_detected then + raise notice 'sqlcode:%,sqlstate:%,sqlerrm:%',sqlcode,sqlstate,sqlerrm; +end; +/ +--执行结果 +NOTICE: sqlcode:-1,sqlstate:-1,sqlerrm: 1: non-GaussDB Exception +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-14-package.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-14-package.md new file mode 100644 index 00000000..a0c422cc --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-14-package.md @@ -0,0 +1,21 @@ +--- +title: package +summary: package +author: Guo Huan +date: 2022-04-27 +--- + +# package + +package是一组相关存储过程、函数、变量、常量、游标等PL/SQL程序的组合,具有面向对象的特点,可以对PL/SQL程序设计元素进行封装。package中的函数具有统一性,创建、删除、修改都统一进行。 + +package包含包头(Package Specification)和Package Body两个部分,其中包头所包含的声明可以被外部函数、匿名块等访问,而在包体中包含的声明不能被外部函数、匿名块等访问,只能被包体内函数和存储过程等访问。 + +PACKAGE的创建请参见[CREATE PACKAGE](../../reference-guide/sql-syntax/CREATE-PACKAGE.md)。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: +> +> - 跨PACKAGE变量不支持作为FOR循环中控制变量使用。 +> - PACKAGE中定义类型不支持删除、修改等操作,也不支持定义表。 +> - 不支持以SCHEMA.PACKAGE.CUROSR的形式引用cursor变量。 +> - 带参数的CURSOR仅支持在当前PACKAGE内打开。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-2-data-types.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-2-data-types.md new file mode 100644 index 00000000..37ba2809 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-2-data-types.md @@ -0,0 +1,10 @@ +--- +title: 数据类型 +summary: 数据类型 +author: Guo Huan +date: 2021-03-04 +--- + +# 数据类型 + +数据类型是一组值的集合以及定义在这个值集上的一组操作。MogDB数据库是由表的集合组成的,而各表中的列定义了该表,每一列都属于一种数据类型,MogDB根据数据类型有相应函数对其内容进行操作,例如MogDB可对数值型数据进行加、减、乘、除操作。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-3-data-type-conversion.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-3-data-type-conversion.md new file mode 100644 index 00000000..9d5e85bd --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-3-data-type-conversion.md @@ -0,0 +1,42 @@ +--- +title: 数据类型转换 +summary: 数据类型转换 +author: Guo Huan +date: 2021-03-04 +--- + +# 数据类型转换 + +数据库中允许有些数据类型进行隐式类型转换(赋值、函数调用的参数等),有些数据类型间不允许进行隐式数据类型转换,可尝试使用MogDB提供的类型转换函数,例如CAST进行数据类型强转。 + +MogDB数据库常见的隐式类型转换,请参见[表1](#隐式类型转换表)。 + +> **须知:** +> MogDB支持的DATE的效限范围是: 公元前4713年到公元294276年。 + +**表 1** 隐式类型转换表 + +| 原始数据类型 | 目标数据类型 | 备注 | +| :----------- | :----------- | :--------------------------- | +| CHAR | VARCHAR2 | - | +| CHAR | NUMBER | 原数据必须由数字组成。 | +| CHAR | DATE | 原数据不能超出合法日期范围。 | +| CHAR | RAW | - | +| CHAR | CLOB | - | +| VARCHAR2 | CHAR | - | +| VARCHAR2 | NUMBER | 原数据必须由数字组成。 | +| VARCHAR2 | DATE | 原数据不能超出合法日期范围。 | +| VARCHAR2 | CLOB | - | +| NUMBER | CHAR | - | +| NUMBER | VARCHAR2 | - | +| DATE | CHAR | - | +| DATE | VARCHAR2 | - | +| RAW | CHAR | - | +| RAW | VARCHAR2 | - | +| CLOB | CHAR | - | +| CLOB | VARCHAR2 | - | +| CLOB | NUMBER | 原数据必须由数字组成。 | +| INT4 | CHAR | - | +| INT4 | BOOLEAN | - | +| INT4 | CHAR | - | +| BOOLEAN | INT4 | - | diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-4-arrays-and-records.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-4-arrays-and-records.md new file mode 100644 index 00000000..f5ad6e31 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-4-arrays-and-records.md @@ -0,0 +1,198 @@ +--- +title: 数组、集合和record +summary: 数组、集合和record +author: Guo Huan +date: 2021-03-04 +--- + +# 数组、集合和record + +## 数组 + +**数组类型的使用** + +在使用数组之前,需要自定义一个数组类型。 + +在存储过程中紧跟AS关键字后面定义数组类型。定义方法如下。 + +``` +TYPE array_type IS VARRAY(size) OF data_type; +``` + +其中: + +- array_type: 要定义的数组类型名。 +- VARRAY: 表示要定义的数组类型。 +- size: 取值为正整数,表示可以容纳的成员的最大数量。 +- data_type: 要创建的数组中成员的类型。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明:** +> +> - 在MogDB中,数组会自动增长,访问越界会返回一个NULL,不会报错。 +> - 在存储过程中定义的数组类型,其作用域仅在该存储过程中。 +> - 建议选择上述定义方法的一种来自定义数组类型,当同时使用两种方法定义同名的数组类型时,MogDB会优先选择存储过程中定义的数组类型来声明数组变量。 +> - data_type也可以为存储过程中定义的record类型(匿名块不支持),但不可以为存储过程中定义的数组或集合类型。 + +MogDB支持使用圆括号来访问数组元素,且还支持一些特有的函数,如extend、count、first、last、prior、exists、 trim、next、delete来访问数组的内容。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明:** +> +> - 存储过程中如果有DML语句(SELECT、UPDATE、INSERT、DELETE),DML语句推荐使用中括号来访问数组元素,使用小括号默认识别为数组访问,若数组不存在,则识别为函数表达式。 +> - 存储过程中的table of类型、record类型、clob作为出入参、游标、raise info等对大于1GB的clob类型不支持。 + +## 集合 + +**集合类型的使用** + +在使用集合之前,需要自定义一个集合类型。 + +在存储过程中紧跟AS关键字后面定义集合类型。定义方法如下。 + +![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/arrays-and-records-2.png) + +其中: + +- table_type:要定义的集合类型名。 +- TABLE:表示要定义集合类型。 +- data_type:要创建的集合中成员的类型。 +- indexby_type: 创建集合索引的类型。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> - 在MogDB中,集合会自动增长,访问越界会返回一个NULL,不会报错。 +> - 在存储过程中定义的集合类型,其作用域仅在该存储过程中。 +> - 索引的类型仅支持integer和varchar类型,其中varchar的长度暂不约束。 +> - NOT NULL只支持语法不支持功能。 +> - data_type可以为存储过程内定义的record类型,集合类型(匿名块不支持),不可以为数组类型。 +> - 不支持跨package的嵌套集合类型变量使用。 +> - 不支持record嵌套table of index by类型的变量作为存储过程的出入参。 +> - 不支持table of index by类型的变量作为函数的出入参。 +> - 不支持通过raise info打印整个嵌套table of变量。 +> - 不支持跨自治事务传递table of变量。 +> - 不支持存储过程的出入参定义为嵌套table of类型。 + +MogDB支持使用圆括号来访问集合元素,且还支持一些特有的函数,如extend、count、first、last、prior、next、delete来访问集合的内容。 + +集合函数支持multiset union/intersect/except all/distinct函数。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明**: +> +> 同一个表达式里不支持两个以上table of index by类型变量的函数调用。 + +## record + +**record**类型的变量 + +创建一个record变量的方式: + +定义一个record类型 ,然后使用该类型来声明一个变量。 + +**语法** + +record类型的语法参见[图1](#record类型的语法)。 + +**图 1** record类型的语法 + +![record类型的语法](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/arrays-and-records-1.png) + +对以上语法格式的解释如下: + +- record_type: 声明的类型名称。 +- field: record类型中的成员名称。 +- datatype: record类型中成员的类型。 +- expression: 设置默认值的表达式。 + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif) **说明:** +> +> 在MogDB中: +> +> - record类型变量的赋值支持: +> - 在函数或存储过程的声明阶段,声明一个record类型,并且可以在该类型中定义成员变量。 +> - 一个record变量到另一个record变量的赋值。 +> - SELECT INTO和FETCH向一个record类型的变量中赋值。 +> - 将一个NULL值赋值给一个record变量。 +> - 不支持INSERT和UPDATE语句使用record变量进行插入数据和更新数据。 +> - 如果成员有复合类型,在声明阶段不支持指定默认值,该行为同声明阶段的变量一样。 +> - date_type也可以为存储过程中定义的record类型、数组类型和集合类型(匿名块不支持)。 + +**示例** + +```sql +下面示例中用到的表定义如下: +MogDB=# \d emp_rec + Table "public.emp_rec" + Column | Type | Modifiers +----------+--------------------------------+----------- + empno | numeric(4,0) | not null + ename | character varying(10) | + job | character varying(9) | + mgr | numeric(4,0) | + hiredate | timestamp(0) without time zone | + sal | numeric(7,2) | + comm | numeric(7,2) | + deptno | numeric(2,0) | + +--演示在函数中对数组进行操作。 +MogDB=# CREATE OR REPLACE FUNCTION regress_record(p_w VARCHAR2) +RETURNS +VARCHAR2 AS $$ +DECLARE + + --声明一个record类型. + type rec_type is record (name varchar2(100), epno int); + employer rec_type; + + --使用%type声明record类型 + type rec_type1 is record (name emp_rec.ename%type, epno int not null :=10); + employer1 rec_type1; + + --声明带有默认值的record类型 + type rec_type2 is record ( + name varchar2 not null := 'SCOTT', + epno int not null :=10); + employer2 rec_type2; + CURSOR C1 IS select ename,empno from emp_rec order by 1 limit 1; + +BEGIN + --对一个record类型的变量的成员赋值。 + employer.name := 'WARD'; + employer.epno = 18; + raise info 'employer name: % , epno:%', employer.name, employer.epno; + + --将一个record类型的变量赋值给另一个变量。 + employer1 := employer; + raise info 'employer1 name: % , epno: %',employer1.name, employer1.epno; + + --将一个record类型变量赋值为NULL。 + employer1 := NULL; + raise info 'employer1 name: % , epno: %',employer1.name, employer1.epno; + + --获取record变量的默认值。 + raise info 'employer2 name: % ,epno: %', employer2.name, employer2.epno; + + --在for循环中使用record变量 + for employer in select ename,empno from emp_rec order by 1 limit 1 + loop + raise info 'employer name: % , epno: %', employer.name, employer.epno; + end loop; + + --在select into 中使用record变量。 + select ename,empno into employer2 from emp_rec order by 1 limit 1; + raise info 'employer name: % , epno: %', employer2.name, employer2.epno; + + --在cursor中使用record变量。 + OPEN C1; + FETCH C1 INTO employer2; + raise info 'employer name: % , epno: %', employer2.name, employer2.epno; + CLOSE C1; + RETURN employer.name; +END; +$$ +LANGUAGE plpgsql; + +--调用该函数。 +MogDB=# CALL regress_record('abc'); + +--删除函数。 +MogDB=# DROP FUNCTION regress_record; +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-5-declare-syntax.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-5-declare-syntax.md new file mode 100644 index 00000000..b204032e --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-5-declare-syntax.md @@ -0,0 +1,82 @@ +--- +title: 声明语法 +summary: 声明语法 +author: Guo Huan +date: 2021-03-04 +--- + +# 声明语法 + +## 基本结构 + +**结构** + +PL/SQL块中可以包含子块,子块可以位于PL/SQL中任何部分。PL/SQL块的结构如下: + +- 声明部分:声明PL/SQL用到的变量、类型、游标、局部的存储过程和函数。 + + ```sql + DECLARE + ``` + + > **说明:** + > 不涉及变量声明时声明部分可以没有。 + > + > - 对匿名块来说,没有变量声明部分时,可以省去DECLARE关键字。 + > - 对存储过程来说,没有DECLARE, AS相当于DECLARE。即便没有变量声明的部分,关键字AS也必须保留。 + +- 执行部分:过程及SQL语句,程序的主要部分。必选。 + + ```sql + BEGIN + ``` + +- 执行异常部分:错误处理。可选。 + + ```sql + EXCEPTION + ``` + +- 结束 + + ```sql + END; + / + ``` + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知:** + > 禁止在PL/SQL块中使用连续的Tab,连续的Tab可能会造成在使用gsql工具带“-r”参数执行PL/SQL块时出现异常。 + +**分类** + +PL/SQL块可以分为以下几类: + +- 匿名块:动态构造,只能执行一次。语法请参考[图1](#anonymous_block::=)。 +- 子程序:存储在数据库中的存储过程、函数、操作符和高级包等。当在数据库上建立好后,可以在其他程序中调用它们。 + +## 匿名块 + +匿名块(Anonymous Block)一般用于不频繁执行的脚本或不重复进行的活动。它们在一个会话中执行,并不被存储。 + +**语法** + +匿名块的语法参见[图1](#anonymous_block::=)。 + +**图 1** anonymous_block::= + +![anonymous_block](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/declare-syntax-1.png) + +对以上语法图的解释如下: + +- 匿名块程序实施部分,以BEGIN语句开始,以END语句停顿,以一个分号结束。输入“/”按回车执行它。 + + > **须知**: + > 最后的结束符”/“必须独占一行,不能直接跟在END后面。 + +- 声明部分包括变量定义、类型、游标定义等。 + +- 最简单的匿名块不执行任何命令。但一定要在任意实施块里至少有一个语句,甚至是一个NULL语句。 + +## 子程序 + +存储在数据库中的存储过程、函数、操作符和高级包等。当在数据库上建立好后,可以在其他程序中调用它们。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-6-basic-statements.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-6-basic-statements.md new file mode 100644 index 00000000..0e565c70 --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-6-basic-statements.md @@ -0,0 +1,215 @@ +--- +title: 基本语句 +summary: 基本语句 +author: Guo Huan +date: 2021-03-04 +--- + +# 基本语句 + +在编写PL/SQL过程中,会定义一些变量,给变量赋值,调用其他存储过程等。介绍PL/SQL中的基本语句,包括定义变量、赋值语句、调用语句以及返回语句。 + +> **说明**: +> 尽量不要在存储过程中调用包含密码的SQL语句,因为存储在数据库中的存储过程文本可能被其他有权限的用户看到导致密码信息被泄漏。如果存储过程中包含其他敏感信息也需要配置存储过程的访问权限,保证敏感信息不会泄漏。 + +## 定义变量 + +介绍PL/SQL中变量的声明,以及该变量在代码中的作用域。 + +**变量声明** + +变量声明语法请参见[图1](#declare_variable::=)。 + +**图 1** declare_variable::= + +![declare_variable](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/basic-statements-1.png) + +对以上语法格式的解释如下: + +- variable_name:变量名。 +- type:变量类型。 +- value:该变量的初始值(如果不给定初始值,则初始为NULL)。value也可以是表达式。 + +**示例** + +```sql +MogDB=# DECLARE + emp_id INTEGER := 7788; --定义变量并赋值 +BEGIN + emp_id := 5*7784; --变量赋值 +END; +/ +``` + +变量类型除了支持基本类型,还可以是使用%TYPE和%ROWTYPE去声明一些与其他表字段或表结构本身相关的变量。 + +**%TYPE属性** + +%TYPE主要用于声明某个与其他变量类型(例如,表中某列的类型)相同的变量。假如我们想定义一个my_name变量,它的变量类型与employee的firstname类型相同,我们可以通过如下定义: + +``` +my_name employee.firstname%TYPE +``` + +这样定义可以带来两个好处,首先,我们不用预先知道employee表的firstname类型具体是什么。其次,即使之后firstname类型有了变化,我们也不需要再次修改my_name的类型。 + +``` +TYPE employee_record is record (id INTEGER, firstname VARCHAR2(20)); +my_employee employee_record; +my_id my_employee.id%TYPE; +my_id_copy my_id%TYPE; +``` + +**%ROWTYPE属性** + +%ROWTYPE属性主要用于对一组数据的类型声明,用于存储表中的一行数据或从游标匹配的结果。假如,我们需要一组数据,该组数据的字段名称与字段类型都与employee表相同。我们可以通过如下定义: + +``` +my_employee employee%ROWTYPE +``` + +同样可以使用在cursor上面,该组数据的字段名称与字段类型都与employee表相同(对于PACKAGE中的cursor,可以省略%ROWTYPE)。%TYPE也可以引用cursor中某一列的类型,我们可以通过如下定义: + +``` +cursor cur is select * from employee; +my_employee cur%ROWTYPE +my_name cur.firstname%TYPE +my_employee2 cur -- 对于PACKAGE中定义的cursor,可以省略%ROWTYPE字段 +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: +> +> - %TYPE不支持引用复合类型或RECORD类型变量的类型、RECORD类型的某列类型、跨PACKAGE复合类型变量的某列类型、跨PACKAGE cursor变量的某列类型等。 +> - %ROWTYPE不支持引用复合类型或RECORD类型变量的类型、跨PACKAGE cursor的类型。 + +**变量作用域** + +变量的作用域表示变量在代码块中的可访问性和可用性。只有在它的作用域内,变量才有效。 + +- 变量必须在declare部分声明,即必须建立BEGIN-END块。块结构也强制变量必须先声明后使用,即变量在过程内有不同作用域、不同的生存期。 +- 同一变量可以在不同的作用域内定义多次,内层的定义会覆盖外层的定义。 +- 在外部块定义的变量,可以在嵌套块中使用。但外部块不能访问嵌套块中的变量。 + +## 赋值语句 + +**语法** + +给变量赋值的语法请参见[图2](#assignment_value::=)。 + +**图 2** assignment_value::= + +![assignment_value](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/basic-statements-2.png) + +对以上语法格式的解释如下: + +- variable_name:变量名。 +- value:可以是值或表达式。值value的类型需要和变量variable_name的类型兼容才能正确赋值。 + +**示例** + +```sql +MogDB=# DECLARE + emp_id INTEGER := 7788;--赋值 +BEGIN + emp_id := 5;--赋值 + emp_id := 5*7784; +END; +/ +``` + +**嵌套赋值** + +给变量嵌套赋值的语法请参见[图3](#nested_assignment_value)。 + +**图 3** nested_assignment_value::= + +![nested_assignment_value](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/basic-statements-3.png) + +对以上语法格式的解释如下: + +- variable_name:变量名。 +- col_name:列名。 +- subscript:下标,针对数组变量使用,可以是值或表达式,类型必须为int。 +- value:可以是值或表达式。值value的类型需要和变量variable_name的类型兼容才能正确赋值。 + +**示例** + +```sql +MogDB=# CREATE TYPE o1 as (a int, b int); +MogDB=# DECLARE + TYPE r1 is VARRAY(10) of o1; + emp_id r1; +BEGIN + emp_id(1).a := 5;--赋值 + emp_id(1).b := 5*7784; +END; +/ +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: +> +> - INTO 方式赋值仅支持对第一层列赋值,且不支持二维及以上数组; +> - 引用嵌套的列值时,若存在数组下标,目前仅支持在前三层列中只存在一个小括号情况,建议使用方括号[ ]引用下标; + +**INTO/BULK COLLECT INTO** + +将存储过程内语句返回的值存储到变量内,BULK COLLECT INTO允许将部分或全部返回值暂存到数组内部。 + +示例: + +```sql +MogDB=# DECLARE + my_id integer; +BEGIN + select id into my_id from customers limit 1; -- 赋值 +END; +/ + +MogDB=# DECLARE + type id_list is varray(6) of customers.id%type; + id_arr id_list; +BEGIN + select id bulk collect into id_arr from customers order by id DESC limit 20; -- 批量赋值 +END; +/ +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知**: BULK COLLECT INTO 只支持批量赋值给数组。合理使用LIMIT字段避免操作过量数据导致性能下降。 + +## 调用语句 + +**语法** + +调用一个语句的语法请参见[图4](#call_clause::=)。 + +**图 4** call_clause::= + +![call_clause](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/basic-statements-4.png) + +对以上语法格式的解释如下: + +- procedure_name:存储过程名。 +- parameter:存储过程的参数,可以没有或者有多个参数。 + +**示例** + +```sql +--创建存储过程proc_staffs +MogDB=# CREATE OR REPLACE PROCEDURE proc_staffs +( +section NUMBER(6), +salary_sum out NUMBER(8,2), +staffs_count out INTEGER +) +IS +BEGIN +SELECT sum(salary), count(*) INTO salary_sum, staffs_count FROM hr.staffs where section_id = section; +END; +/ + +--调用存储过程proc_return. +MogDB=# CALL proc_staffs(2,8,6); + +--清除存储过程 +MogDB=# DROP PROCEDURE proc_staffs; +``` diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-7-dynamic-statements.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-7-dynamic-statements.md new file mode 100644 index 00000000..b98094fd --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-7-dynamic-statements.md @@ -0,0 +1,166 @@ +--- +title: 动态语句 +summary: 动态语句 +author: Guo Huan +date: 2021-03-04 +--- + +# 动态语句 + +## 执行动态查询语句 + +介绍执行动态查询语句。MogDB提供EXECUTE IMMEDIATE和OPEN FOR两种方式实现动态查询。EXECUTE IMMEDIATE是通过动态执行SELECT语句,OPEN FOR是结合了游标的使用。当需要将查询的结果保存在一个数据集用于提取时,可使用OPEN FOR实现动态查询。 + +**EXECUTE IMMEDIATE** + +语法图请参见[图1](#图1)。 + +**图 1** EXECUTE IMMEDIATE dynamic_select_clause::= + +![EXECUTE-IMMEDIATE-dynamic_select_clause](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-1.png) + +using_clause子句的语法图参见[图2](#图2)。 + +**图 2** using_clause::= + +![using_clause](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-2.png) + +对以上语法格式的解释如下: + +- define_variable:用于指定存放单行查询结果的变量。 + +- USING IN bind_argument:用于指定存放传递给动态SQL值的变量,即在dynamic_select_string中存在占位符时使用。 + +- USING OUT bind_argument:用于指定存放动态SQL返回值的变量。 + + > ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif) **须知:** + > + > - 查询语句中,into和out不能同时存在; + > - 占位符命名以“:”开始,后面可跟数字、字符或字符串,与USING子句的bind_argument一一对应; + > - bind_argument只能是值、变量或表达式,不能是表名、列名、数据类型等数据库对象,即不支持使用bind_argument为动态SQL语句传递模式对象。如果存储过程需要通过声明参数传递数据库对象来构造动态SQL语句(常见于执行DDL语句时),建议采用连接运算符“||”拼接dynamic_select_clause; + > - 动态PL/SQL块允许出现重复的占位符,即相同占位符只能与USING子句的一个bind_argument按位置对应。 + +**OPEN FOR** + +动态查询语句还可以使用OPEN FOR打开动态游标来执行。 + +语法参见[图3](#图3)。 + +**图 3** open_for::= + +![open_for](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-3.png) + +参数说明: + +- cursor_name:要打开的游标名。 +- dynamic_string:动态查询语句。 +- USING value:在dynamic_string中存在占位符时使用。 + +游标的使用请参考[游标](1-11-cursors.md)。 + +## 执行动态非查询语句 + +**语法** + +语法请参见[图4](#noselect::=)。 + +**图 4** noselect::= + +![noselect](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-4.png) + +using_clause子句的语法参见[图5](#using_clause::=)。 + +**图 5** using_clause::= + +![using_clause-0](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-5.png) + +对以上语法格式的解释如下: + +USING IN bind_argument用于指定存放传递给动态SQL值的变量,在dynamic_noselect_string中存在占位符时使用,即动态SQL语句执行时,bind_argument将替换相对应的占位符。要注意的是,bind_argument只能是值、变量或表达式,不能是表名、列名、数据类型等数据库对象。如果存储过程需要通过声明参数传递数据库对象来构造动态SQL语句(常见于执行DDL语句时),建议采用连接运算符“||”拼接dynamic_select_clause。另外,动态语句允许出现重复的占位符,相同占位符只能与唯一一个bind_argument按位置一一对应。 + +**示例** + +```sql +--创建表 +MogDB=# CREATE TABLE sections_t1 +( + section NUMBER(4) , + section_name VARCHAR2(30), + manager_id NUMBER(6), + place_id NUMBER(4) +); + +--声明变量 +MogDB=# DECLARE + section NUMBER(4) := 280; + section_name VARCHAR2(30) := 'Info support'; + manager_id NUMBER(6) := 103; + place_id NUMBER(4) := 1400; + new_colname VARCHAR2(10) := 'sec_name'; +BEGIN +--执行查询 + EXECUTE IMMEDIATE 'insert into sections_t1 values(:1, :2, :3, :4)' + USING section, section_name, manager_id,place_id; +--执行查询(重复占位符) + EXECUTE IMMEDIATE 'insert into sections_t1 values(:1, :2, :3, :1)' + USING section, section_name, manager_id; +--执行ALTER语句(建议采用"||"拼接数据库对象构造DDL语句) + EXECUTE IMMEDIATE 'alter table sections_t1 rename section_name to ' || new_colname; +END; +/ + +--查询数据 +MogDB=# SELECT * FROM sections_t1; + +--删除表 +MogDB=# DROP TABLE sections_t1; +``` + +## 动态调用存储过程 + +动态调用存储过程必须使用匿名的语句块将存储过程或语句块包在里面,使用EXECUTE IMMEDIATE…USING语句后面带IN、OUT来输入、输出参数。 + +**语法** + +语法请参见[图6](#call_procedure::=)。 + +**图 6** call_procedure::= + +![call_procedure](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-6.png) + +using_clause子句的语法参见[图7](#using_clause)。 + +**图 7** using_clause::= + +![using_clause-1](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-7.png) + +对以上语法格式的解释如下: + +- CALL procedure_name:调用存储过程。 +- [:placeholder1,:placeholder2,…]:存储过程参数占位符列表。占位符个数与参数个数相同。 +- USING [IN|OUT|IN OUT] bind_argument:用于指定存放传递给存储过程参数值的变量。bind_argument前的修饰符与对应参数的修饰符一致。 + +## 动态调用匿名块 + +动态调用匿名块是指在动态语句中执行匿名块,使用EXECUTE IMMEDIATE…USING语句后面带IN、OUT来输入、输出参数。 + +**语法** + +语法请参见[图8](#call_anonymous_block::=)。 + +**图 8** call_anonymous_block::= + +![call_anonymous_block](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-8.png) + +using_clause子句的语法参见[图9](#using_clause::)。 + +**图 9** using_clause::= + +![using_clause-2](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/dynamic-statements-9.png) + +对以上语法格式的解释如下: + +- 匿名块程序实施部分,以BEGIN语句开始,以END语句停顿,以一个分号结束。 +- USING [IN|OUT|IN OUT] bind_argument,用于指定存放传递给存储过程参数值的变量。bind_argument前的修饰符与对应参数的修饰符一致。 +- 匿名块中间的输入输出参数使用占位符来指明,要求占位符个数与参数个数相同,并且占位符所对应参数的顺序和USING中参数的顺序一致。 +- 目前MogDB在动态语句调用匿名块时,EXCEPTION语句中暂不支持使用占位符进行输入输出参数的传递。 diff --git a/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-8-control-statements.md b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-8-control-statements.md new file mode 100644 index 00000000..4a15ccbd --- /dev/null +++ b/product/zh/docs-mogdb/v3.1/developer-guide/plpgsql/1-8-control-statements.md @@ -0,0 +1,651 @@ +--- +title: 控制语句 +summary: 控制语句 +author: Guo Huan +date: 2021-03-04 +--- + +# 控制语句 + +## 返回语句 + +MogDB提供两种方式返回数据:RETURN或RETURN NEXT及RETURN QUERY。其中,RETURN NEXT和RETURN QUERY只适用于函数,不适用存储过程。 + +### RETURN + +**语法** + +返回语句的语法请参见[图1](#return_clause)。 + +**图 1** return_clause::= + + ![return_clause](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-1.jpg) + +对以上语法的解释如下: + +用于将控制从存储过程或函数返回给调用者。 + +**示例** + +请参见调用语句的[示例](1-6-basic-statements.md#调用语句)。 + +### RETURN NEXT及RETURN QUERY + +**语法** + +创建函数时需要指定返回值SETOF datatype。 + +return_next_clause::= + + ![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-2.png) + +return_query_clause::= + + ![img](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-3.png) + +对以上语法的解释如下: + +当需要函数返回一个集合时,使用RETURN NEXT或者RETURN QUERY向结果集追加结果,然后继续执行函数的下一条语句。随着后续的RETURN NEXT或RETURN QUERY命令的执行,结果集中会有多个结果。函数执行完成后会一起返回所有结果。 + +RETURN NEXT可用于标量和复合数据类型。 + +RETURN QUERY有一种变体RETURN QUERY EXECUTE,后面还可以增加动态查询,通过USING向查询插入参数。 + +**示例** + +```sql +MogDB=# CREATE TABLE t1(a int); +MogDB=# INSERT INTO t1 VALUES(1),(10); + +--RETURN NEXT +MogDB=# CREATE OR REPLACE FUNCTION fun_for_return_next() RETURNS SETOF t1 AS $$ +DECLARE + r t1%ROWTYPE; +BEGIN + FOR r IN select * from t1 + LOOP + RETURN NEXT r; + END LOOP; + RETURN; +END; +$$ LANGUAGE PLPGSQL; +MogDB=# call fun_for_return_next(); + a +--- + 1 + 10 +(2 rows) + +-- RETURN QUERY +MogDB=# CREATE OR REPLACE FUNCTION fun_for_return_query() RETURNS SETOF t1 AS $$ +DECLARE + r t1%ROWTYPE; +BEGIN + RETURN QUERY select * from t1; +END; +$$ +language plpgsql; +MogDB=# call fun_for_return_query(); + a +--- + 1 + 10 +(2 rows) +``` + +## 条件语句 + +条件语句的主要作用判断参数或者语句是否满足已给定的条件,根据判定结果执行相应的操作。 + +MogDB有五种形式的IF: + +- IF_THEN + + **图 2** IF_THEN::= + + ![IF_THEN](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-4.jpg) + + IF_THEN语句是IF的最简单形式。如果条件为真,statements将被执行。否则,将忽略它们的结果使该IF_THEN语句执行结束。 + + **示例** + + ```sql + MogDB=# IF v_user_id <> 0 THEN + UPDATE users SET email = v_email WHERE user_id = v_user_id; + END IF; + ``` + +- IF_THEN_ELSE + + **图 3** IF_THEN_ELSE::= + + ![IF_THEN_ELSE](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-5.jpg) + + IF_THEN_ELSE语句增加了ELSE的分支,可以声明在条件为假的时候执行的语句。 + + **示例** + + ```sql + MogDB=# IF parentid IS NULL OR parentid = '' + THEN + RETURN; + ELSE + hp_true_filename(parentid);--表示调用存储过程 + END IF; + ``` + +- IF_THEN_ELSE IF + + I F语句可以嵌套,嵌套方式如下: + + ```bash + MogDB=# IF sex = 'm' THEN + pretty_sex := 'man'; + ELSE + IF sex = 'f' THEN + pretty_sex := 'woman'; + END IF; + END IF; + ``` + + 这种形式实际上就是在一个IF语句的ELSE部分嵌套了另一个IF语句。因此需要一个END IF语句给每个嵌套的IF,另外还需要一个END IF语句结束父IF-ELSE。如果有多个选项,可使用下面的形式。 + +- IF_THEN_ELSIF_ELSE + + **图 4** IF_THEN_ELSIF_ELSE::= + + ![IF_THEN_ELSIF_ELSE](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-6.png) + + **示例** + + ```bash + IF number_tmp = 0 THEN + result := 'zero'; + ELSIF number_tmp > 0 THEN + result := 'positive'; + ELSIF number_tmp < 0 THEN + result := 'negative'; + ELSE + result := 'NULL'; + END IF; + ``` + +- IF_THEN_ELSEIF_ELSE + + ELSEIF是ELSIF的别名。 + + 综合示例 + + ```sql + CREATE OR REPLACE PROCEDURE proc_control_structure(i in integer) + AS + BEGIN + IF i > 0 THEN + raise info 'i:% is greater than 0. ',i; + ELSIF i < 0 THEN + raise info 'i:% is smaller than 0. ',i; + ELSE + raise info 'i:% is equal to 0. ',i; + END IF; + RETURN; + END; + / + + CALL proc_control_structure(3); + + --删除存储过程 + DROP PROCEDURE proc_control_structure; + ``` + +## 循环语句 + +**简单LOOP语句** + +**语法图** + +**图 5** loop::= + + ![loop](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-7.png) + +**示例** + +```sql +CREATE OR REPLACE PROCEDURE proc_loop(i in integer, count out integer) +AS + BEGIN + count:=0; + LOOP + IF count > i THEN + raise info 'count is %. ', count; + EXIT; + ELSE + count:=count+1; + END IF; + END LOOP; + END; +/ + +CALL proc_loop(10,5); +``` + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-notice.gif)**须知**: +> +> 该循环必须要结合EXIT使用,否则将陷入死循环。 + +**WHILE_LOOP语句** + +**语法图** + +**图 6** while_loop::= + + ![while_loop](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-8.png) + +只要条件表达式为真,WHILE语句就会不停的在一系列语句上进行循环,在每次进入循环体的时候进行条件判断。 + +**示例** + +```sql +CREATE TABLE integertable(c1 integer) ; +CREATE OR REPLACE PROCEDURE proc_while_loop(maxval in integer) +AS + DECLARE + i int :=1; + BEGIN + WHILE i < maxval LOOP + INSERT INTO integertable VALUES(i); + i:=i+1; + END LOOP; + END; +/ + +--调用函数 +CALL proc_while_loop(10); + +--删除存储过程和表 +DROP PROCEDURE proc_while_loop; +DROP TABLE integertable; +``` + +**FOR_LOOP(integer变量)语句** + +**语法图** + +**图 7** for_loop::= + + ![for_loop](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-9.png) + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明:** +> +> - 变量name会自动定义为integer类型并且只在此循环里存在。变量name介于lower_bound和upper_bound之间。 +> - 当使用REVERSE关键字时,lower_bound必须大于等于upper_bound,否则循环体不会被执行。 + +**FOR_LOOP查询语句** + +**语法图** + +**图 8** for_loop_query::= + + ![for_loop_query](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-10.png) + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明:** +> 变量target会自动定义,类型和query的查询结果的类型一致,并且只在此循环中有效。target的取值就是query的查询结果。 + +**FORALL批量查询语句** + +**语法图** + +**图 9** forall::= + + ![forall](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-16.png) + +> ![img](https://cdn-mogdb.enmotech.com/docs-media/icon/icon-note.gif)**说明:** +> +> - 变量index会自动定义为integer类型并且只在此循环里存在。index的取值介于low_bound和upper_bound之间。 +> - 如果声明了SAVE EXCEPTIONS,则会将循环体DML执行过程中每次遇到的异常保存在SQL&BULK_EXCEPTIONS中,并在执行结束后统一抛出一个异常,循环过程中没有异常的执行的结果在当前子事务内不会回滚。 + +**示例** + +```sql +CREATE TABLE hdfs_t1 ( + title NUMBER(6), + did VARCHAR2(20), + data_peroid VARCHAR2(25), + kind VARCHAR2(25), + interval VARCHAR2(20), + time DATE, + isModified VARCHAR2(10) +); + +INSERT INTO hdfs_t1 VALUES( 8, 'Donald', 'OConnell', 'DOCONNEL', '650.507.9833', to_date('21-06-1999', 'dd-mm-yyyy'), 'SH_CLERK' ); + +CREATE OR REPLACE PROCEDURE proc_forall() +AS +BEGIN + FORALL i IN 100..120 + update hdfs_t1 set title = title + 100*i; +END; +/ + +--调用函数 +CALL proc_forall(); + +--查询存储过程调用结果 +SELECT * FROM hdfs_t1 WHERE title BETWEEN 100 AND 120; + +--删除存储过程和表 +DROP PROCEDURE proc_forall; +DROP TABLE hdfs_t1; +``` + +## 分支语句 + +**语法** + +分支语句的语法请参见[图10](#case_when)。 + +**图 10** case_when::= + + ![case_when](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-12.png) + +when_clause子句的语法图参见[图11](#when_clause)。 + +**图 11** when_clause::= + + ![when_clause](https://cdn-mogdb.enmotech.com/docs-media/mogdb/developer-guide/control-statements-13.png) + +参数说明: + +- case_expression:变量或表达式。 +- when_expression:常量或者条件表达式。 +- statement:执行语句。 + +**示例** + +```sql +CREATE OR REPLACE PROCEDURE proc_case_branch(pi_result in integer, pi_return out integer) +AS + BEGIN + CASE pi_result + WHEN 1 THEN + pi_return := 111; + WHEN 2 THEN + pi_return := 222; + WHEN 3 THEN + pi_return := 333; + WHEN 6 THEN + pi_return := 444; + WHEN 7 THEN + pi_return := 555; + WHEN 8 THEN + pi_return := 666; + WHEN 9 THEN + pi_return := 777; + WHEN 10 THEN + pi_return := 888; + ELSE + pi_return := 999; + END CASE; + raise info 'pi_return : %',pi_return ; +END; +/ + +CALL proc_case_branch(3,0); + +--删除存储过程 +DROP PROCEDURE proc_case_branch; +``` + +## 空语句 + +在PL/SQL程序中,可以用NULL语句来说明“不用做任何事情”,相当于一个占位符,可以使某些语句变得有意义,提高程序的可读性。 + +**语法** + +空语句的用法如下: + +```sql +DECLARE + … +BEGIN + … + IF v_num IS NULL THEN + NULL; -- 不需要处理任何数据。 + END IF; +END; +/ +``` + +## 错误捕获语句 + +缺省时,当PL/SQL函数执行过程中发生错误时退出函数执行,并且周围的事务也会回滚。可以用一个带有EXCEPTION子句的BEGIN块捕获错误并且从中恢复。其语法是正常的BEGIN块语法的一个扩展: + +```sql +[<