數(shù)據(jù)庫(kù)文檔，可以說(shuō)是數(shù)據(jù)庫(kù)的“臉面”，是了解學(xué)習(xí)數(shù)據(jù)庫(kù)的主要手段。近些年國(guó)內(nèi)數(shù)據(jù)庫(kù)產(chǎn)品層出不窮，使用者也是眼花繚亂。如何選擇、學(xué)習(xí)掌握一款數(shù)據(jù)庫(kù)產(chǎn)品，我的經(jīng)驗(yàn)就是可以先從文檔入手。之前也接觸過(guò)不少國(guó)內(nèi)數(shù)據(jù)庫(kù)產(chǎn)品，在文檔上與如Oracle、MySQL等還存在不小差距，這點(diǎn)還需國(guó)內(nèi)廠商更多重視文檔工作。畢竟一份文檔是否寫的完整、詳實(shí)、準(zhǔn)確，關(guān)系到用戶是否能用好一款產(chǎn)品。下文是我根據(jù)之前的觀察，總結(jié)的一份個(gè)人認(rèn)為較為完整的數(shù)據(jù)庫(kù)產(chǎn)品文檔結(jié)構(gòu)。希望對(duì)上手一個(gè)新數(shù)據(jù)庫(kù)，有所幫助。

1、產(chǎn)品簡(jiǎn)介

文檔的第一個(gè)部分是產(chǎn)品簡(jiǎn)介，用戶需要從這部分快速了解一個(gè)產(chǎn)品，并做出判斷是否符合自己的需求。因此這一部分不需要涉及很多技術(shù)細(xì)節(jié)，更多是描述“是什么、做什么”的問(wèn)題。讓受眾能夠有簡(jiǎn)單、直觀的了解即可。

（1）產(chǎn)品概述

產(chǎn)品概述部分，需要準(zhǔn)確描述產(chǎn)品的定位，即“是什么”的問(wèn)題。不要以為說(shuō)清楚這個(gè)問(wèn)題很簡(jiǎn)單，很多產(chǎn)品連這個(gè)就基礎(chǔ)問(wèn)題都沒有說(shuō)清楚。舉個(gè)例子，如國(guó)外有一款產(chǎn)品Vitess，其官網(wǎng)主頁(yè)定位為“Scalable. Reliable. MySQL-compatible. Cloud-native. Database.”，通過(guò)這樣一系列名詞能讓我們對(duì)產(chǎn)品有個(gè)大致的印象。這里有個(gè)誤區(qū)，盡量不要使用一些含糊的描述，如“企業(yè)級(jí)、金融級(jí)..”等描述。上述描述對(duì)用戶了解產(chǎn)品沒有任何幫助，屬于無(wú)用信息。

（2）適用場(chǎng)景

適用場(chǎng)景部分，將在“是什么”的基礎(chǔ)上，進(jìn)一步說(shuō)明在產(chǎn)品在哪些場(chǎng)景有價(jià)值。通過(guò)這部分說(shuō)明，讓用戶可以更加具象地理解產(chǎn)品的使用范圍。若描述很精準(zhǔn)，甚至可以做到對(duì)號(hào)入座，讓用戶可以明確的知道是否適合自己。這里的場(chǎng)景可以很寬泛，因?yàn)樽鳛橥ㄓ眯援a(chǎn)品來(lái)說(shuō)，只要描述大致即可。具體到某一行業(yè)、某類業(yè)務(wù)，可以通過(guò)解決方案層面進(jìn)行說(shuō)明。

（3）核心功能

上面的產(chǎn)品描述，使我們了解的產(chǎn)品“是什么”，那么核心功能部分就挑重點(diǎn)說(shuō)明下產(chǎn)品“做什么”?？梢酝ㄟ^(guò)產(chǎn)品支持的具體功能進(jìn)行說(shuō)明。這里需要說(shuō)明的是，這里的功能應(yīng)該是對(duì)用戶有明確場(chǎng)景價(jià)值的，有實(shí)際受益的功能。例如某數(shù)據(jù)庫(kù)產(chǎn)品支持“彈性伸縮”，用戶就可以了解當(dāng)業(yè)務(wù)出現(xiàn)徒增時(shí)，是可以實(shí)現(xiàn)靈活的擴(kuò)容。避免出現(xiàn)一些偏重于技術(shù)性的功能描述，如“數(shù)據(jù)分片策略支持一致性Hash方式”，這樣非技術(shù)背景的同學(xué)很難知道這意味著什么。

（4）核心技術(shù)

有了場(chǎng)景和功能描述，下面就可以說(shuō)明實(shí)現(xiàn)上述功能使用哪些核心技術(shù)，這是可以“秀肌肉”的環(huán)節(jié)，目的是使用戶更深入地了解功能實(shí)現(xiàn)原理，更加篤信產(chǎn)品能力。在核心技術(shù)選擇上，更多傾向于與前面核心功能能夠有對(duì)應(yīng)關(guān)系，即通過(guò)什么技術(shù)實(shí)現(xiàn)某種功能、進(jìn)而延展為適用某些場(chǎng)景。這樣就形成從“技術(shù)-功能-場(chǎng)景”的閉環(huán)。

（5）產(chǎn)品架構(gòu)

產(chǎn)品架構(gòu)部分，可通過(guò)一張簡(jiǎn)圖，說(shuō)明產(chǎn)品組成。注意這里不是技術(shù)架構(gòu)、部署架構(gòu)，而是產(chǎn)品架構(gòu)，因此無(wú)需關(guān)注實(shí)現(xiàn)細(xì)節(jié)，重點(diǎn)是讓用戶能快速了解產(chǎn)品是如何組成的，與上下游如何協(xié)同工作等就可以了。很多細(xì)節(jié)的如系統(tǒng)與子系統(tǒng)組成、技術(shù)棧和框架、接口和協(xié)議、數(shù)據(jù)架構(gòu)和流程等是可以忽略了，避免對(duì)用戶造成干擾。

（6）產(chǎn)品規(guī)格與版本

這部分是在用戶對(duì)產(chǎn)品定位、功能、技術(shù)有了一定了解后，說(shuō)明下產(chǎn)品規(guī)格和版本，激發(fā)下潛在購(gòu)買意愿。很多產(chǎn)品都提供了個(gè)人版、標(biāo)準(zhǔn)版、企業(yè)版等不同版本或者提供了多種規(guī)格可供用戶選擇，這里需要明示出來(lái)，特別需重點(diǎn)說(shuō)明不同版本、規(guī)格的差異，方便用戶根據(jù)自身情況進(jìn)行選擇。特別建議通過(guò)一個(gè)列表的形式進(jìn)行說(shuō)明，一目了然。

（7）兼容性說(shuō)明

很多國(guó)產(chǎn)數(shù)據(jù)庫(kù)產(chǎn)品采用了兼容性設(shè)計(jì)，其背后原因是希望借助其他產(chǎn)品成熟生態(tài)進(jìn)行擴(kuò)展。常見如兼容大型商業(yè)數(shù)據(jù)庫(kù)（如Oracle）或流行的開源數(shù)據(jù)庫(kù)（如MySQL、PostgreSQL）。對(duì)于很多用戶來(lái)說(shuō)，接受一個(gè)全新的數(shù)據(jù)庫(kù)產(chǎn)品還是有一定難度的，如果有兼容性則可以大大降低使用門檻。當(dāng)然兼容性是多方位的，包括開發(fā)、管理、監(jiān)控等等，可通過(guò)對(duì)比的方式讓用戶快速了解。

（8）使用限制

沒有產(chǎn)品是完美的，清楚的知道產(chǎn)品邊界對(duì)用戶很有意義。通過(guò)這些限制，可以很好地掌握想使用這一產(chǎn)品需要做哪些“妥協(xié)”。事前的知悉遠(yuǎn)比事后暴露出問(wèn)題重要的多，也是對(duì)用戶負(fù)責(zé)任的一種態(tài)度。

2、快速上手

快速上手部分，是讓用戶在最短的時(shí)間內(nèi)，體驗(yàn)產(chǎn)品功能，完成一個(gè)使用閉環(huán)。這其中需包括從部署安裝、開發(fā)設(shè)計(jì)到應(yīng)用開發(fā)等多個(gè)階段。在體驗(yàn)場(chǎng)景設(shè)計(jì)上，可選擇最小功能為設(shè)計(jì)原則，能快速完成即可。如可能涉及到多個(gè)組件，也盡量減少來(lái)回交互，盡量通過(guò)在單一產(chǎn)品完成操作。

（1）安裝部署

在安裝部署方面，可不循序最佳實(shí)踐，能快速完成即可。很多產(chǎn)品都提供了如一鍵安裝、All in One包、Docker鏡像、云實(shí)例等方式，盡量降低安裝部署難度、降低對(duì)客戶端環(huán)境依賴。一般要求在五分鐘內(nèi)可以完成環(huán)境準(zhǔn)備工作，時(shí)間過(guò)長(zhǎng)用戶會(huì)失去體驗(yàn)?zāi)托摹Ｒ苑植际綌?shù)據(jù)庫(kù)為例，其涉及的組件非常多，安裝過(guò)程可能很復(fù)雜，提供快捷體驗(yàn)環(huán)境尤為重要。以分布式數(shù)據(jù)庫(kù)-KunlunBase為例，就通過(guò)Docker鏡像的方式，可在數(shù)分鐘內(nèi)完成一套包括多個(gè)計(jì)算節(jié)點(diǎn)、存儲(chǔ)節(jié)點(diǎn)的集群構(gòu)建過(guò)程，非常方便。

（2）用戶操作

用戶操作部分，主要是為了配合后面體驗(yàn)工作所必需的操作。常見的如實(shí)例啟停、用戶創(chuàng)建、權(quán)限分配等。完整的管理操作不需要在此說(shuō)明，也不建議通過(guò)圖形化界面完成，盡量通過(guò)同一終端就可以完成整個(gè)操作。

（3）SQL操作

SQL 操作部分，用戶最為常用的SQL操作，通常包括表和索引的創(chuàng)建刪除，數(shù)據(jù)記錄的CRUD，簡(jiǎn)單查詢（含表關(guān)聯(lián)），事務(wù)操作等。通過(guò)以上部分，小白用戶可達(dá)到日?？捎玫某潭?。

（4）應(yīng)用開發(fā)

進(jìn)一步進(jìn)階的要求是如何通用應(yīng)用程序訪問(wèn)數(shù)據(jù)庫(kù)。這其中建議針對(duì)常用的開發(fā)語(yǔ)言支持情況進(jìn)行描述，例如Java、Python、Go、C/C++等。每種語(yǔ)言中又包括前提條件（如語(yǔ)言版本）、驅(qū)動(dòng)方式（含鏈接）、示例代碼（完整源碼）、編譯運(yùn)行等說(shuō)明。針對(duì)簡(jiǎn)單場(chǎng)景，完全可以仿照這一過(guò)程進(jìn)行開發(fā)。

（5）導(dǎo)入導(dǎo)出

導(dǎo)入導(dǎo)出部分，是為了方便生態(tài)集成?？蓪F(xiàn)有系統(tǒng)數(shù)據(jù)通過(guò)導(dǎo)入功能快速集成到新數(shù)據(jù)庫(kù)中，也可以將數(shù)據(jù)庫(kù)中內(nèi)容通過(guò)導(dǎo)出輸出到其他平臺(tái)。上述示例，可以幫助用戶完成一些更為復(fù)雜的示例，不用從0到1完全自己創(chuàng)建，可以復(fù)用現(xiàn)有的結(jié)構(gòu)、數(shù)據(jù)及SQL，快速體驗(yàn)產(chǎn)品能力。

（6）性能測(cè)試

在完成了上述試用后，用戶最后通常會(huì)關(guān)注到性能。針對(duì)性能部分，可利用標(biāo)準(zhǔn)性能測(cè)試，如TPC-C、TPC-H、TPC-DS等。在內(nèi)容中需包含完整的測(cè)試步驟，方便用戶可以照此快速?gòu)?fù)現(xiàn)測(cè)試過(guò)程并提供最終測(cè)試數(shù)據(jù)。真實(shí)的性能表現(xiàn)還是需要用戶根據(jù)自己業(yè)務(wù)進(jìn)行測(cè)試，上述僅僅是供用戶參考即可。很多用戶也會(huì)基于此作為選項(xiàng)參考因素之一。上述內(nèi)容也獨(dú)立成章，形成性能白皮書。

3、部署安裝

安裝部署，通常是了解使用數(shù)據(jù)庫(kù)的第一步。與前面的快速上手不同，這一環(huán)節(jié)盡量做到詳實(shí)、完整，個(gè)中細(xì)節(jié)需要描述到位。

（1）安裝部署

由于數(shù)據(jù)庫(kù)，通常存在多種規(guī)格或部署模式，在描述安裝之前應(yīng)先說(shuō)明下大體情況、適用場(chǎng)景等，然后再針對(duì)不同安裝情況分別加以說(shuō)明。如果數(shù)據(jù)庫(kù)包含多種組件（特別是分布式數(shù)據(jù)庫(kù)），這種情況很常見，可以說(shuō)明下各組件功能，并描述獨(dú)立安裝過(guò)程，由用戶選擇是否安裝。對(duì)于同時(shí)提供多種安裝方式，如命令行、圖形化、容器化安裝方式的，也應(yīng)分別說(shuō)明。在具體安裝過(guò)程中，可遵循硬件、系統(tǒng)、環(huán)境、用戶、初始化、安裝、啟動(dòng)、組件、檢測(cè)等環(huán)節(jié)分別加以說(shuō)明。

（2）數(shù)據(jù)庫(kù)卸載

卸載，往往是很多產(chǎn)品文檔會(huì)忽略的一個(gè)環(huán)節(jié)。如何干凈、徹底地刪除數(shù)據(jù)庫(kù)，是需要遵循一定步驟的。通常應(yīng)包括備份（數(shù)據(jù)+配置）、停止實(shí)例、刪除空間、刪除用戶、檢查殘留等。

（3）數(shù)據(jù)庫(kù)升級(jí)

數(shù)據(jù)庫(kù)升級(jí)是不可避免的操作，特別是在產(chǎn)品不完善的情況下。而對(duì)于用戶來(lái)說(shuō)，升級(jí)往往是比較痛苦的，如何做到升級(jí)平滑是DBA非常關(guān)注的問(wèn)題。特別是在分布式環(huán)境下，組件多、節(jié)點(diǎn)多，升級(jí)能力更為重要。在整體升級(jí)中，可包括升級(jí)檢查、影響評(píng)估、升級(jí)準(zhǔn)備、數(shù)據(jù)備份、配置備份、實(shí)例升級(jí)、組件升級(jí)、狀態(tài)檢查、應(yīng)用驗(yàn)證、升級(jí)回退等環(huán)節(jié)進(jìn)行說(shuō)明。

（4）數(shù)據(jù)庫(kù)擴(kuò)縮容

數(shù)據(jù)庫(kù)擴(kuò)縮容分為兩種情況，一種是所謂Scale UP，一種是Scale Out。前者更多是單機(jī)或集中式架構(gòu)的場(chǎng)景擴(kuò)容策略，這種更多是硬件的升級(jí)，這里不再詳述。后者則更多是分布式數(shù)據(jù)庫(kù)的通常擴(kuò)容策略，很多數(shù)據(jù)庫(kù)都采用存算分離架構(gòu)，支持對(duì)計(jì)算、存儲(chǔ)或其他組件的擴(kuò)容。這其中的核心問(wèn)題一是是否支持在線擴(kuò)容，二是是否需要移動(dòng)數(shù)據(jù)。之前接觸不少用戶，針對(duì)這塊還是比較慎重的，需要在擴(kuò)容過(guò)程中重點(diǎn)說(shuō)明對(duì)線上運(yùn)行的影響及過(guò)程跟蹤?？s容的過(guò)程跟擴(kuò)容類似，但需關(guān)注存儲(chǔ)空間、算力等的減少或降低對(duì)系統(tǒng)的影響。

（5）云與容器化

很多數(shù)據(jù)庫(kù)，也提供了云端產(chǎn)品。云作為一種新型資源供給方式，顛覆了傳統(tǒng)使用行為，大大加速簡(jiǎn)化了基礎(chǔ)設(shè)施的構(gòu)建及使用。作為云產(chǎn)品，安裝部署、管理維護(hù)、監(jiān)控告警、備份優(yōu)化等都可以依托于云平臺(tái)去完成。在安裝部署階段，用戶可以不再關(guān)心具體的安裝配置過(guò)程，而需要更多關(guān)心云的一些特殊性。如選擇數(shù)據(jù)庫(kù)產(chǎn)品、高可用架構(gòu)、部署區(qū)域、網(wǎng)絡(luò)拓?fù)?、存?chǔ)介質(zhì)等以及是否購(gòu)買使用其他產(chǎn)品。此處文檔中只需描述這些特殊點(diǎn)，解決用戶選擇困難即可。針對(duì)支持容器化管理的情況，也可以一并說(shuō)明如何使用管理數(shù)據(jù)庫(kù)。具體操作可以參見后面參考引用部分。

4、數(shù)據(jù)庫(kù)管理

數(shù)據(jù)庫(kù)管理，主要是面向DBA人群，重點(diǎn)說(shuō)明數(shù)據(jù)庫(kù)管理的相關(guān)內(nèi)容。這部分的內(nèi)容會(huì)比較龐雜，需要分解說(shuō)明。

（1）集群管理

這其中包括實(shí)例及相關(guān)組件的啟動(dòng)、停止、狀態(tài)查看。其他如增加、刪除組件及節(jié)點(diǎn)，可以參考之前的“數(shù)據(jù)庫(kù)擴(kuò)縮容”；數(shù)據(jù)庫(kù)升降級(jí)可參考之前的“數(shù)據(jù)庫(kù)升降級(jí)”。

（2）租戶管理

如數(shù)據(jù)庫(kù)支持租戶，可在此處說(shuō)明下，主要包括租戶創(chuàng)建、刪除、資源配置等。有些產(chǎn)品租戶能力較強(qiáng)，實(shí)現(xiàn)了較為完整的租戶能力，包括資源、參數(shù)、備份、監(jiān)控、診斷等，這種情況建議在將租戶管理放在數(shù)據(jù)庫(kù)管理章節(jié)最后，獨(dú)立說(shuō)明。

（3）參數(shù)管理

一個(gè)數(shù)據(jù)庫(kù)會(huì)保護(hù)很多參數(shù)，特別是分布式數(shù)據(jù)庫(kù)，不同組件也會(huì)有各自的參數(shù)。此部分需要說(shuō)明參數(shù)的大致分類、操作方式（查看、修改、重置）、持久化情況等信息。至于參數(shù)的明細(xì)，可以在參考引用部分重點(diǎn)說(shuō)明，包括但不限于參數(shù)名稱、參數(shù)含義、值域范圍、作用域（實(shí)例級(jí)、組件級(jí)、會(huì)話級(jí)等）、生效方式（在線、離線）等。這里強(qiáng)調(diào)下，有些產(chǎn)品是基于開源數(shù)據(jù)庫(kù)實(shí)現(xiàn)或兼容其他數(shù)據(jù)庫(kù)產(chǎn)品，需重點(diǎn)說(shuō)明下“其他數(shù)據(jù)庫(kù)”參數(shù)在當(dāng)前產(chǎn)品是否有變化，并給出具體描述，不能直接引用其他產(chǎn)品說(shuō)明。

（4）日志管理

數(shù)據(jù)庫(kù)系統(tǒng)中會(huì)包含很多日志，如常見的運(yùn)行日志、事務(wù)日志、告警日志、監(jiān)聽日志、慢日志等。在此部分需要說(shuō)明日志文件分類、文件名稱、內(nèi)容格式、存儲(chǔ)位置、配置方法、歸檔刪除策略等。如日志內(nèi)容需要單獨(dú)工具解讀，也可以一并在此說(shuō)明。日志是用戶觀察數(shù)據(jù)庫(kù)的一個(gè)窗口，特別在很多產(chǎn)品性能視圖、事件等機(jī)制尚不完善的情況下，因此應(yīng)更加重視日志的使用。

（5）存儲(chǔ)管理

存儲(chǔ)管理部分，涉及數(shù)據(jù)庫(kù)運(yùn)行時(shí)所需空間的管理，這里需根據(jù)不同文件對(duì)于空間、IO能力等訴求的差異，在前期就做好規(guī)劃。后續(xù)日常管理則包括空間的擴(kuò)容、移動(dòng)、監(jiān)控、清理等。對(duì)于很多數(shù)據(jù)庫(kù)，還支持?jǐn)?shù)據(jù)副本的概念，即數(shù)據(jù)存儲(chǔ)多份，針對(duì)這種情況也需在此說(shuō)明，包括工作原理等；如能人為干預(yù)副本的分配、移動(dòng)、分裂、合并等也一并說(shuō)明。

（6）備份恢復(fù)

備份恢復(fù)部分，包括物理與邏輯備份恢復(fù)兩種。一般建議將邏輯的備份恢復(fù)，歸為導(dǎo)入導(dǎo)出，放在后面的數(shù)據(jù)集成章節(jié)，這里重點(diǎn)談物理備份恢復(fù)。在開始部分可先說(shuō)明備份介質(zhì)選擇、各組件備份（如數(shù)據(jù)、日志、配置等）。在具體備份操作上，包括備份創(chuàng)建、備份刪除、過(guò)程跟蹤、備份限流、備份集管理等。在具體恢復(fù)操作上，包括完整恢復(fù)、基于時(shí)點(diǎn)恢復(fù)、部分恢復(fù)（如基于對(duì)象）等。

（7）故障診斷

故障診斷部分，建議先說(shuō)明下整體故障診斷的框架，即支持哪些故障診斷的方法及手段，然后再具體說(shuō)明。常見的診斷如健康檢查（如存儲(chǔ)壞塊等）、日常巡檢（如工作負(fù)載、參數(shù)配置等）、DUMP文件（各類異常生成）、錯(cuò)誤碼等。此部分需說(shuō)明上述各類操作方法，具體DUMP文件格式解讀、錯(cuò)誤碼信息可以引導(dǎo)參考引用部分。

（8）監(jiān)控指標(biāo)

監(jiān)控是DBA觀察數(shù)據(jù)庫(kù)的主要窗口，這其中包括數(shù)據(jù)字典視圖、動(dòng)態(tài)性能視圖以及系統(tǒng)可吐出的各種Metric。此部分建議先說(shuō)明下監(jiān)控體系、收集機(jī)制、查詢方法、指標(biāo)分類及解讀等。具體的視圖、Metric 說(shuō)明可引導(dǎo)參數(shù)引用部分。

（9）應(yīng)急處理

應(yīng)急處理，是指系統(tǒng)過(guò)載或出現(xiàn)異常時(shí)需要緊急采取的措施。應(yīng)急處理的首要目的并不是排查根因，而是快速止血，先讓數(shù)據(jù)庫(kù)盡快恢復(fù)正常服務(wù)能力。這里可根據(jù)經(jīng)驗(yàn)收集經(jīng)驗(yàn)，按異常類別進(jìn)行分類說(shuō)明。如硬件故障、業(yè)務(wù)過(guò)載、組件異常等，然后整理對(duì)應(yīng)應(yīng)急處理措施。

5、高可用

高可用意味著兩點(diǎn)，一是服務(wù)高可用，二是數(shù)據(jù)高可靠。前者是為了保障業(yè)務(wù)系統(tǒng)的可用性，后者為為了保護(hù)企業(yè)核心資產(chǎn)-數(shù)據(jù)不丟失。針對(duì)整體高可用，可以在前面先概述下整體高可用技術(shù)，包括各種高可用架構(gòu)，后面再分類說(shuō)明。

（1）實(shí)例高可用

在實(shí)例內(nèi)部，已經(jīng)內(nèi)置有多種高可用能力。例如針對(duì)應(yīng)用連接，Oracle 數(shù)據(jù)庫(kù)支持的TAF；針對(duì)存儲(chǔ)異常，很多數(shù)據(jù)庫(kù)提供的多存儲(chǔ)副本機(jī)制；針對(duì)誤操作等，數(shù)據(jù)庫(kù)提供如數(shù)據(jù)閃回功能；針對(duì)組件級(jí)故障，數(shù)據(jù)庫(kù)提供的自動(dòng)切換等。上述這些均為高可用在實(shí)例內(nèi)能夠提供的技術(shù)能力，可在此說(shuō)明。

（2）集群高可用

高可用集群是指在實(shí)例高可用基礎(chǔ)外，通過(guò)架構(gòu)支持多種集群方式以滿足更高的可用性。當(dāng)實(shí)例或單點(diǎn)集群出現(xiàn)故障時(shí)，可以切換到高可用集群的其他部分來(lái)承載。這其中可以有多種模式，常見的如主備、分布式和共享三種。主備模式，是指將主庫(kù)/主集群數(shù)據(jù)復(fù)制一份到備庫(kù)/備集群，后者可承擔(dān)異常時(shí)切換滿足業(yè)務(wù)訪問(wèn)或者承擔(dān)只讀訪問(wèn)需求。類似于Oracle DataGuard、MySQL Replication 方式。分布式模式，是指數(shù)據(jù)庫(kù)本身各組件節(jié)點(diǎn)采用分布式架構(gòu)，當(dāng)異常時(shí)可通過(guò)冗余節(jié)點(diǎn)來(lái)處理。例如在存算分離架構(gòu)下，計(jì)算節(jié)點(diǎn)多采用多點(diǎn)冗余無(wú)狀態(tài)設(shè)計(jì)，存儲(chǔ)節(jié)點(diǎn)采用多數(shù)據(jù)副本的方式解決單點(diǎn)，管理節(jié)點(diǎn)也多采用主備或基于共識(shí)協(xié)議方式解決。類似于 Google Spanner、OceanBase、TiDB、TDSQL等產(chǎn)品。共享模式則是指多個(gè)數(shù)據(jù)庫(kù)實(shí)例作為計(jì)算節(jié)點(diǎn)共享一份存儲(chǔ)（或加緩存）的方式，上層計(jì)算實(shí)例出現(xiàn)問(wèn)題，可自動(dòng)切換，下層的共享存儲(chǔ)則通過(guò)硬件或分布式存儲(chǔ)來(lái)解決。類似于 Oracle RAC 的方案即如此，國(guó)內(nèi)如DM DSC、華為開源的參天引擎等。

（3）部署實(shí)踐：同城與異地

針對(duì)各種高可用方案，用戶很關(guān)心如何選擇及部署。這里可根據(jù)最為常用的幾個(gè)高可用場(chǎng)景說(shuō)下上述架構(gòu)的部署方式。這其中包括針對(duì)同城（同機(jī)房）、同城（跨機(jī)房）、異地多種場(chǎng)景進(jìn)行說(shuō)明。比較高效的方式是畫下部署圖，這樣比較清晰。此外，針對(duì)各種異常情況，不同場(chǎng)景及架構(gòu)下的系統(tǒng)可用性（例如RTO、RPO指標(biāo)）情況，這樣用戶可以一目了然。

（4）高可用管理

針對(duì)上述高可用能力的相關(guān)操作，包括各種架構(gòu)的搭建、切換、同步、監(jiān)控、排障等。

6、產(chǎn)品安全

一個(gè)安全的數(shù)據(jù)庫(kù)系統(tǒng)應(yīng)該能夠建立安全保護(hù)機(jī)制，保護(hù)計(jì)算機(jī)硬件、軟件和數(shù)據(jù)不因偶然和惡意的原因而遭到破壞、更改和泄漏。對(duì)數(shù)據(jù)庫(kù)的安全性要求通常會(huì)被劃分為保密性、完整性、可用性三個(gè)要素。保密性是指數(shù)據(jù)不能泄露給非授權(quán)用戶，通常通過(guò)數(shù)據(jù)加密、訪問(wèn)控制等方式實(shí)現(xiàn)。完整性是指數(shù)據(jù)在存儲(chǔ)和傳輸過(guò)程中，數(shù)據(jù)不被破壞及丟失，通常通過(guò)訪問(wèn)控制、完整性校驗(yàn)來(lái)實(shí)現(xiàn)?？捎眯允侵笖?shù)據(jù)可被授權(quán)用戶，在異常時(shí)可恢復(fù)使用，通常通過(guò)備份、冗余、防火墻等方式來(lái)實(shí)現(xiàn)。

（1）傳輸加密

傳輸加密是指在應(yīng)用與數(shù)據(jù)庫(kù)之間或數(shù)據(jù)庫(kù)各組件之間使用 SSL/TLS 的方式實(shí)現(xiàn)通信加密。使用加密傳輸可以減少數(shù)據(jù)庫(kù)中敏感信息的泄露風(fēng)險(xiǎn)，有效保護(hù)數(shù)據(jù)的安全。有些數(shù)據(jù)庫(kù)產(chǎn)品是兼容開源數(shù)據(jù)庫(kù)協(xié)議的，這時(shí)就需要判斷是否已支持開源數(shù)據(jù)庫(kù)的傳輸加密。

（2）鑒權(quán)認(rèn)證

鑒權(quán)認(rèn)證，是指對(duì)登錄數(shù)據(jù)庫(kù)訪問(wèn)數(shù)據(jù)的用戶進(jìn)行身份驗(yàn)證，確認(rèn)該用戶是否能夠與某一個(gè)數(shù)據(jù)庫(kù)用戶進(jìn)行關(guān)聯(lián)，并根據(jù)關(guān)聯(lián)的數(shù)據(jù)庫(kù)用戶的權(quán)限，對(duì)該用戶在數(shù)據(jù)庫(kù)中的數(shù)據(jù)訪問(wèn)活動(dòng)進(jìn)行安全控制。有些數(shù)據(jù)庫(kù)產(chǎn)品還支持操作系統(tǒng)認(rèn)證，即使用操作系統(tǒng)用戶直接登錄，也需一并說(shuō)明。

（3）訪問(wèn)控制（用戶、角色、權(quán)限）

訪問(wèn)控制，是指數(shù)據(jù)庫(kù)通過(guò)用戶、角色、權(quán)限設(shè)計(jì)，做到對(duì)資源訪問(wèn)控制管理，不同用戶或角色擔(dān)負(fù)不同的責(zé)任。在權(quán)限設(shè)計(jì)上，一般分為系統(tǒng)權(quán)限、對(duì)象權(quán)限，并提供一組視圖來(lái)查看權(quán)限信息。有些數(shù)據(jù)庫(kù)產(chǎn)品還擴(kuò)展支持了三權(quán)分立、行級(jí)權(quán)限、網(wǎng)絡(luò)安全等能力。

（4）數(shù)據(jù)加密

數(shù)據(jù)加密，狹義上指對(duì)數(shù)據(jù)庫(kù)存儲(chǔ)數(shù)據(jù)的加密，廣義則還包括對(duì)日志、備份、過(guò)程定義等的加密。通過(guò)數(shù)據(jù)加密可以有效的保護(hù)，避免因數(shù)據(jù)外泄造成的損失。現(xiàn)在大部分?jǐn)?shù)據(jù)庫(kù)都實(shí)現(xiàn)了透明加密（即TDE），加密與解密的過(guò)程對(duì)使用者來(lái)說(shuō)是完全透明的。但這里需要關(guān)注幾點(diǎn)，一是國(guó)密算法、密鑰輪轉(zhuǎn)等是否支持；二是數(shù)據(jù)加密后備份恢復(fù)或上下游生態(tài)是否受到影響。

（5）安全審計(jì)

安全審計(jì)，是指對(duì)具備相應(yīng)權(quán)限用戶執(zhí)行操作的記錄，進(jìn)而防止用戶登錄信息泄露，或者訪問(wèn)權(quán)限被濫用。審計(jì)功能可以加強(qiáng)企業(yè)對(duì)數(shù)據(jù)安全、合規(guī)等方面的要求，是跟蹤用戶行為最主要的工具。此部分應(yīng)包括審計(jì)開啟、查看的方法，及開啟審計(jì)對(duì)性能影響的說(shuō)明。

（6）防火墻

防火墻功能，更多是在事前或事中針對(duì)訪問(wèn)做的一種防御措施，用于檢測(cè)和防御外部入侵風(fēng)險(xiǎn)，較為常見的如IP白名單等。

7、開發(fā)指南

前面幾個(gè)章節(jié)多為面向運(yùn)維側(cè)，后面幾個(gè)章節(jié)更多是面對(duì)架構(gòu)、研發(fā)側(cè)，講述如何基于這個(gè)數(shù)據(jù)庫(kù)開發(fā)應(yīng)用系統(tǒng)。

（1）連接驅(qū)動(dòng)

在開發(fā)之初，先需解決如何連接訪問(wèn)問(wèn)題，因此需說(shuō)明連接驅(qū)動(dòng)問(wèn)題。面對(duì)常見的開發(fā)語(yǔ)言\接口，如何連接數(shù)據(jù)。常見如Java、Python、C/C++、Go、.NET，接口如JDBC、ODBC、OLEDB等。此處最好給出連接驅(qū)動(dòng)下載地址及簡(jiǎn)單開發(fā)示例。某些產(chǎn)品兼容其他數(shù)據(jù)庫(kù)，即可以通過(guò)其他數(shù)據(jù)庫(kù)協(xié)議訪問(wèn)，也需一并說(shuō)明。

（2）QL元素

針對(duì)SQL語(yǔ)句使用的最基本要素的說(shuō)明，包括字面值、標(biāo)識(shí)符、雙引號(hào)、對(duì)象及對(duì)象命令、偽列（如有）、NULL等的說(shuō)明。

（3）數(shù)據(jù)類型

支持?jǐn)?shù)據(jù)類型，包括類型、存儲(chǔ)長(zhǎng)度、值域、精度等信息，最好以一種表格的形式呈現(xiàn)。為了方便用戶理解，也可以同步列出主流數(shù)據(jù)庫(kù)類型的對(duì)應(yīng)關(guān)系，這樣方便用戶參照轉(zhuǎn)換。

（4）字符集

系統(tǒng)支持字符集的情況，并說(shuō)明字符集使用規(guī)范。

（5）運(yùn)算符

數(shù)據(jù)庫(kù)支持的運(yùn)算符，包括但不限于算術(shù)、比較、邏輯、連接、位、其他運(yùn)算符。

（6）函數(shù)

數(shù)據(jù)支持的函數(shù)說(shuō)明，包括但不限于日期、字符、數(shù)學(xué)、轉(zhuǎn)換、聚焦、窗口、特殊函數(shù)等。如果系統(tǒng)還支持自定義函數(shù)，可在下面的語(yǔ)句開發(fā)部分詳細(xì)說(shuō)明。

（7）語(yǔ)句開發(fā)

語(yǔ)句開發(fā)部分，大體可分為兩個(gè)部分：SQL語(yǔ)言和過(guò)程語(yǔ)言。這其中包含的內(nèi)容有比較多，其中SQL語(yǔ)言就包括DDL\DML\DQL\TCL等，又可以進(jìn)一步分解如DQL就可以細(xì)分為查詢、過(guò)濾、關(guān)聯(lián)、嵌套、層次等。過(guò)程化語(yǔ)言則包括語(yǔ)法結(jié)構(gòu)、條件控制、數(shù)據(jù)操作、數(shù)據(jù)游標(biāo)等。這部分只描述基本內(nèi)容即可，具體寫法可參考后面的參考引用。此外，還可包含如注釋等寫法。

（8）結(jié)構(gòu)設(shè)計(jì)

數(shù)據(jù)庫(kù)支持很多種對(duì)象，包括常見的表、分區(qū)、分片、索引、視圖、觸發(fā)器、存儲(chǔ)過(guò)程、序列等。在結(jié)構(gòu)設(shè)計(jì)部分，需說(shuō)明各對(duì)象的設(shè)計(jì)規(guī)范，包括基礎(chǔ)命名規(guī)范、設(shè)計(jì)規(guī)范、最佳實(shí)踐等。相較于之前傳統(tǒng)數(shù)據(jù)庫(kù)，如今數(shù)據(jù)庫(kù)在開發(fā)設(shè)計(jì)上需關(guān)注側(cè)重點(diǎn)有了明顯的變化。如在分布式數(shù)據(jù)庫(kù)中，數(shù)據(jù)分片尤為重要；數(shù)倉(cāng)數(shù)據(jù)庫(kù)中列存表的設(shè)計(jì)有其特有要求；多模數(shù)據(jù)庫(kù)，對(duì)架構(gòu)設(shè)計(jì)又有著自己的特殊性等等。這部分內(nèi)容較為繁多，可以結(jié)合案例進(jìn)行說(shuō)明，方便用戶理解。

（9）對(duì)象管理

上面結(jié)構(gòu)設(shè)計(jì)中的諸多對(duì)象，都需要一定管理操作，如創(chuàng)建、刪除、查看、修改、截?cái)?、重建、分析、編譯、執(zhí)行等等，均在此說(shuō)明。

（10）事務(wù)&隔離級(jí)

這其中包括事務(wù)原理性說(shuō)明、事務(wù)控制、異常事務(wù)處理、事務(wù)與并發(fā)、事務(wù)與隔離級(jí)等內(nèi)容的說(shuō)明。針對(duì)事務(wù)的一些小點(diǎn)，如空閑事務(wù)、懸掛事務(wù)處理、顯性與隱性事務(wù)、大事務(wù)處理等，也可在此說(shuō)明。在分布式數(shù)據(jù)庫(kù)下，分布式事務(wù)也需要單獨(dú)說(shuō)明下。

（11）鎖與死鎖

需要說(shuō)明系統(tǒng)鎖的類別、工作機(jī)制、顆粒度、互斥行為、死鎖與死鎖檢測(cè)機(jī)制等。

8、性能調(diào)優(yōu)

當(dāng)系統(tǒng)出現(xiàn)性能瓶頸時(shí)，性能調(diào)優(yōu)就顯得尤為重要。調(diào)優(yōu)本身可以在多個(gè)層次進(jìn)行，這里可按照自下而上或者說(shuō)先局部后總體的方式進(jìn)行說(shuō)明，通常都按照語(yǔ)句級(jí)、對(duì)象級(jí)、實(shí)例級(jí)、系統(tǒng)級(jí)、架構(gòu)級(jí)、應(yīng)用層調(diào)優(yōu)順序來(lái)展開。最后在說(shuō)明下調(diào)優(yōu)相關(guān)工具的使用。

（1）SQL 調(diào)優(yōu)

SQL 語(yǔ)句的調(diào)優(yōu)，首先要理解SQL執(zhí)行過(guò)程，包括解析器、優(yōu)化器、執(zhí)行器的行為，包括緩存、執(zhí)行計(jì)劃等內(nèi)容。在具體描述上也可遵循上面的 SQL 執(zhí)行順序進(jìn)行說(shuō)明，逐步展開。其中優(yōu)化器部分，還會(huì)涉及到統(tǒng)計(jì)信息、參數(shù)化等問(wèn)題。這部分內(nèi)容相對(duì)龐雜，需要細(xì)致說(shuō)明。

（2）對(duì)象調(diào)優(yōu)

對(duì)象的調(diào)優(yōu)，更多是在對(duì)象設(shè)計(jì)階段的一些最佳實(shí)踐，例如是否需要做分片、分區(qū)？是否需創(chuàng)建索引？如何和使用自增效率高等等。這部分可按照對(duì)象分列說(shuō)明。在說(shuō)明過(guò)程中，最好等配合一些查詢、監(jiān)控手段，可以印證調(diào)優(yōu)是否有效。

（3）實(shí)例調(diào)優(yōu)

實(shí)例調(diào)優(yōu)，通常是指各種參數(shù)的優(yōu)化配置。最好的方式是提前建立性能基線，再根據(jù)收集到的信息做調(diào)整。很多數(shù)據(jù)診斷優(yōu)化工具提供的報(bào)告，可以幫助完成實(shí)例調(diào)優(yōu)。

（4）系統(tǒng)調(diào)優(yōu)

系統(tǒng)調(diào)優(yōu)，是指在操作系統(tǒng)或硬件層面可以考慮的一些優(yōu)化手段。

（5）架構(gòu)調(diào)優(yōu)

當(dāng)在單一實(shí)例或集群無(wú)法滿足優(yōu)化結(jié)果，就要考慮在架構(gòu)層面進(jìn)行。例如使用讀寫分離技術(shù)，滿足更高的查詢請(qǐng)求；如使用分布式數(shù)據(jù)庫(kù)提供更強(qiáng)的計(jì)算能力等。這部分相對(duì)代價(jià)比較大了，通常描述些方法論就可以。

（6）應(yīng)用調(diào)優(yōu)

最后部分，就是不要把優(yōu)化僅僅限于數(shù)據(jù)庫(kù)層面，在應(yīng)用層也可以做很多東西。例如通過(guò)引入緩存降低數(shù)據(jù)庫(kù)壓力；通過(guò)應(yīng)用層處理重?cái)?shù)據(jù)庫(kù)負(fù)載的計(jì)算任務(wù)降低壓力等。

（7）調(diào)優(yōu)工具

配合上面的調(diào)優(yōu)工作，需要一組調(diào)優(yōu)工具來(lái)輔助完成。這其中比較重要的如統(tǒng)計(jì)信息，包括收集查看操作；執(zhí)行計(jì)劃，包括查看、管理執(zhí)行計(jì)劃；性能視圖，包括各粒度性能指標(biāo)的查看；性能診斷工具，如Oracle AWR等工具可以完成系統(tǒng)診斷等。

9、數(shù)據(jù)集成

數(shù)據(jù)庫(kù)不是一個(gè)孤立的環(huán)境，需要與上下游生態(tài)打通，這就對(duì)數(shù)據(jù)庫(kù)提供的集成能力提出一定的要求。

（1）數(shù)據(jù)遷移

數(shù)據(jù)遷移是指從其他數(shù)據(jù)庫(kù)將數(shù)據(jù)一次性遷移到當(dāng)前數(shù)據(jù)庫(kù)；或?qū)?dāng)前數(shù)據(jù)庫(kù)遷移到其他庫(kù)。這包括結(jié)構(gòu)遷移和數(shù)據(jù)遷移，其中數(shù)據(jù)遷移又可分解為全量遷移、增量遷移、數(shù)據(jù)對(duì)比等過(guò)程。很多產(chǎn)品都支持了多種遷移工具，可采用列表方式詳細(xì)說(shuō)明。

（2）數(shù)據(jù)同步

數(shù)據(jù)同步是指兩個(gè)數(shù)據(jù)庫(kù)之間保持持續(xù)數(shù)據(jù)復(fù)制狀態(tài)，兩個(gè)庫(kù)之間可以保持準(zhǔn)實(shí)時(shí)的狀態(tài)。在同構(gòu)數(shù)據(jù)庫(kù)下往往可通過(guò)物理或邏輯日志消費(fèi)的方式進(jìn)行，異構(gòu)庫(kù)間相對(duì)難度較大。很多第三方產(chǎn)品提供了異構(gòu)庫(kù)間數(shù)據(jù)同步的能力。

（3）導(dǎo)入導(dǎo)出

除了前面提到的備份恢復(fù)外，異構(gòu)數(shù)據(jù)庫(kù)間進(jìn)行數(shù)據(jù)交換一個(gè)便捷的方式就通過(guò)導(dǎo)入導(dǎo)出方式。通過(guò)將數(shù)據(jù)導(dǎo)出為格式化文件或 SQL 語(yǔ)句的文件，再向目標(biāo)端導(dǎo)入或執(zhí)行，可相對(duì)容易地實(shí)現(xiàn)異構(gòu)庫(kù)數(shù)據(jù)交換。數(shù)據(jù)庫(kù)應(yīng)提供上述導(dǎo)出為文件或語(yǔ)句腳本的能力。

（4）CDC

CDC，是Change Data Capture的縮寫，翻譯過(guò)來(lái)是數(shù)據(jù)變化捕捉。這是一種數(shù)據(jù)集成的能力，通過(guò)將數(shù)據(jù)庫(kù)的變更處理為消息，供下游生態(tài)系統(tǒng)消費(fèi)訪問(wèn)，可以較為容易地實(shí)現(xiàn)數(shù)據(jù)變化的傳播。這也成為數(shù)據(jù)庫(kù)開發(fā)生態(tài)的一種規(guī)范。

10、參考引用

參考引用，是個(gè)“大字典”，文檔中涉及到速查類的信息都可以放在這里，方便用戶快速查找。

（1）SQL 參考

包括SQL語(yǔ)句的寫法、注意事項(xiàng)、典型示例等。由于SQL寫法比較復(fù)雜，可以采用鐵路圖等方式簡(jiǎn)化理解，方便用戶使用。具體使用上可按用途分類，按字母排索引表，便于查找。

（2）PL 參考

過(guò)程化語(yǔ)言參考，包括前面講的如循環(huán)、條件判斷、分支、賦值、游標(biāo)等操作，都在此說(shuō)明。

（3）API 參考

用戶通常與數(shù)據(jù)庫(kù)是通過(guò) SQL 語(yǔ)句打交道，但有時(shí)也會(huì)提供API的方式。例如很多管控類的操作會(huì)提供API供用戶調(diào)用，包括在K8S環(huán)境里集成的Operator也類似。特別是云產(chǎn)品，為了方便用戶集成進(jìn)自己的運(yùn)維系統(tǒng)，也會(huì)提供Open API。這里重點(diǎn)說(shuō)明下API用法、參數(shù)、給出示例即可。

（4）系統(tǒng)變量與參數(shù)

這里重點(diǎn)說(shuō)明變量或參數(shù)的含義、值域、作用域、是否熱加載等信息，給出一份詳細(xì)列表。需注意的是，分布式數(shù)據(jù)庫(kù)有很多組件，需要區(qū)分上述變量或參數(shù)是哪個(gè)組件，是否可以統(tǒng)一設(shè)置等。

（5）錯(cuò)誤碼

包括錯(cuò)誤碼組成、錯(cuò)誤碼含義、錯(cuò)誤碼速查表。如提供了兼容模式，還需說(shuō)明是否兼容原始數(shù)據(jù)庫(kù)的錯(cuò)誤碼，如果兼容一并列出。

（6）告警/等待事件

系統(tǒng)定義的事件，包括告警事件、等待事件或其他事件。通過(guò)這些事件可以有效分析系統(tǒng)運(yùn)行狀態(tài)。

（7）性能視圖/數(shù)據(jù)字典

如前面所談，需要完整的數(shù)據(jù)字典和性能視圖說(shuō)明，方便用戶查詢。

（8）驅(qū)動(dòng)說(shuō)明

不同開發(fā)語(yǔ)言數(shù)據(jù)庫(kù)驅(qū)動(dòng)說(shuō)明，包括驅(qū)動(dòng)支持的主要功能、數(shù)據(jù)類型、函數(shù)等。

（9）保留關(guān)鍵字

系統(tǒng)內(nèi)置保留的關(guān)鍵字。

（10）術(shù)語(yǔ)表

文檔中引用名詞的描述。

（11）工具說(shuō)明

數(shù)據(jù)庫(kù)產(chǎn)品周邊生態(tài)工具的說(shuō)明，一般數(shù)據(jù)庫(kù)產(chǎn)品都會(huì)提供如備份恢復(fù)、導(dǎo)入導(dǎo)出、SQL 命令行等工具。這里需說(shuō)明各工具功能、使用方法、參數(shù)說(shuō)明等。

（12）生態(tài)兼容

生態(tài)兼容是指與數(shù)據(jù)庫(kù)上下游生態(tài)的兼容情況，例如從數(shù)據(jù)建模、數(shù)據(jù)開發(fā)、數(shù)據(jù)分析、數(shù)據(jù)挖掘、可視化展現(xiàn)、數(shù)據(jù)管理、ETL、數(shù)據(jù)庫(kù)管理、備份恢復(fù)、數(shù)據(jù)庫(kù)優(yōu)化、大數(shù)據(jù)平臺(tái)等等，這些上面的主流工具是否支持這一產(chǎn)品。對(duì)于前天就具備兼容性產(chǎn)品來(lái)說(shuō)，是會(huì)較容易的支持，如從0到1完成的新產(chǎn)品會(huì)有一個(gè)過(guò)程。

11、性能測(cè)試

可部分可參考“快速入門”部分，可獨(dú)立成章，包含的測(cè)試內(nèi)容更加詳實(shí)。

12、常見問(wèn)題

FAQ環(huán)節(jié)，針對(duì)用戶經(jīng)常提供的問(wèn)題羅列如此。如問(wèn)題較多，可采用分類或標(biāo)簽的方式，方便用戶檢索。

13、版本發(fā)布記錄

版本發(fā)布記錄，說(shuō)明發(fā)布的主要版本功能、修復(fù)的Bug等。方便用戶根據(jù)此記錄，結(jié)合自己的場(chǎng)景判斷是否需要升級(jí)。