From ada289c6df339c005ac3619aab7ae66d8c255a43 Mon Sep 17 00:00:00 2001 From: Dave Borowitz Date: Tue, 18 Dec 2018 13:24:14 -0800 Subject: [PATCH] Update most documentation for NoteDb Remove outdated references to ReviewDb. Where ambiguous terms like "database" are used, make sure they are still technically accurate, or else remove them. After this change, all documentation should be up to date with respect to the database backend, with the exception of note-db.txt itself. Change-Id: I7134087dc56070788e81ada6ac504b3c8fe84c4c --- Documentation/cmd-create-project.txt | 5 ++--- Documentation/cmd-flush-caches.txt | 2 +- Documentation/cmd-index.txt | 2 +- Documentation/cmd-ls-user-refs.txt | 4 ++-- Documentation/cmd-query.txt | 4 ++-- Documentation/cmd-review.txt | 2 +- Documentation/config-gerrit.txt | 18 ++++++++---------- Documentation/config-robot-comments.txt | 1 - Documentation/dev-contributing.txt | 10 +++++----- Documentation/dev-plugins.txt | 9 ++++----- Documentation/install.txt | 12 +++++------- Documentation/metrics.txt | 4 ---- .../pgm-LocalUsernamesToLowerCase.txt | 2 +- Documentation/pgm-init.txt | 5 ++--- Documentation/pgm-rulec.txt | 3 +-- Documentation/user-upload.txt | 2 +- 16 files changed, 36 insertions(+), 49 deletions(-) diff --git a/Documentation/cmd-create-project.txt b/Documentation/cmd-create-project.txt index 026d7b1f5a..e48eea5766 100644 --- a/Documentation/cmd-create-project.txt +++ b/Documentation/cmd-create-project.txt @@ -28,9 +28,8 @@ _ssh_ -p _gerrit create-project_ == DESCRIPTION Creates a new bare Git repository under `gerrit.basePath`, using the project name supplied. The newly created repository is empty -(has no commits), but is registered in the Gerrit database so that -the initial commit may be uploaded for review, or initial content -can be pushed directly into a branch. +(has no commits), and the initial content may either be uploaded for +review, or pushed directly to a branch. If replication is enabled, this command also connects to each of the configured remote systems over SSH and uses command line git diff --git a/Documentation/cmd-flush-caches.txt b/Documentation/cmd-flush-caches.txt index 55d9083178..5a84b9d7d9 100644 --- a/Documentation/cmd-flush-caches.txt +++ b/Documentation/cmd-flush-caches.txt @@ -16,7 +16,7 @@ Clear an in-memory cache, forcing Gerrit to reconsult the ground truth when it needs the information again. Flushing a cache may be necessary if an administrator modifies -database records directly in the database, rather than going through +NoteDb metadata directly in a repository, rather than going through the Gerrit web interface. If no options are supplied, defaults to `--all`. diff --git a/Documentation/cmd-index.txt b/Documentation/cmd-index.txt index e999218d6d..edb54b5ccb 100644 --- a/Documentation/cmd-index.txt +++ b/Documentation/cmd-index.txt @@ -71,7 +71,7 @@ link:cmd-ls-projects.html[gerrit ls-projects]:: List projects visible to the caller. link:cmd-query.html[gerrit query]:: - Query the change database. + Query the change search index. 'gerrit receive-pack':: 'Deprecated alias for `git receive-pack`.' diff --git a/Documentation/cmd-ls-user-refs.txt b/Documentation/cmd-ls-user-refs.txt index cba7d1bdef..0363f60cf5 100644 --- a/Documentation/cmd-ls-user-refs.txt +++ b/Documentation/cmd-ls-user-refs.txt @@ -32,8 +32,8 @@ Administrators --user:: -u:: Required; User for which the visible refs should be listed. Gerrit - will query the database to find matching users, so the - full identity/name does not need to be specified. + will query the index to find matching users, so the full + identity/name does not need to be specified. --only-refs-heads:: Only list the refs found under refs/heads/* diff --git a/Documentation/cmd-query.txt b/Documentation/cmd-query.txt index 79723c52d0..7eb24eab94 100644 --- a/Documentation/cmd-query.txt +++ b/Documentation/cmd-query.txt @@ -1,7 +1,7 @@ = gerrit query == NAME -gerrit query - Query the change database +gerrit query - Query the change search index == SYNOPSIS [verse] @@ -24,7 +24,7 @@ _ssh_ -p _gerrit query_ == DESCRIPTION -Queries the change database and returns results describing changes +Queries the change search index and returns results describing changes that match the input query. More recently updated changes appear before older changes, which is the same order presented in the web interface. For each matching change, the result contains data diff --git a/Documentation/cmd-review.txt b/Documentation/cmd-review.txt index 5417901e1f..71385e29d4 100644 --- a/Documentation/cmd-review.txt +++ b/Documentation/cmd-review.txt @@ -27,7 +27,7 @@ _ssh_ -p _gerrit review_ == DESCRIPTION Updates the current user's approval status of the specified patch sets and/or submits them for merging, sending out email -notifications and updating the database. +notifications and updating code review metadata. Patch sets may be specified in 'CHANGEID,PATCHSET' format, such as '8242,2', or 'COMMIT' format. diff --git a/Documentation/config-gerrit.txt b/Documentation/config-gerrit.txt index 94ee7abaa1..01db7cebf8 100644 --- a/Documentation/config-gerrit.txt +++ b/Documentation/config-gerrit.txt @@ -46,8 +46,8 @@ Changing this parameter requires to migrate database using the link:pgm-MigrateAccountPatchReviewDb.html[MigrateAccountPatchReviewDb] program. Migration cannot be done while the server is running. + -Also note that the db_name has to be a new db and not reusing gerrit's own review database, -otherwise gerrit's init will remove the table. +Also note that the db_name has to be a new db and not reusing an old ReviewDb +database from a former 2.x site, otherwise gerrit's init will remove the table. ---- [accountPatchReviewDb] @@ -805,11 +805,10 @@ cache `"accounts"`:: + Cache entries contain important details of an active user, including their display name, preferences, and known email addresses. Entry -information is obtained from the `accounts` database table. +information is obtained from NoteDb data in the `All-Users` repo. + -If direct updates are made to any of these database tables, this -cache should be flushed. +If direct updates are made to `All-Users`, this cache should be flushed. cache `"adv_bases"`:: + @@ -2623,8 +2622,7 @@ Defaults to no limit. + Maximum number of leaf terms to allow in a query. Too-large queries may perform poorly, so setting this option causes query parsing to fail fast -before attempting to send them to the secondary index. Should this limit -be reached, database is used instead of index as applicable. +before attempting to send them to the secondary index. + When the index type is `LUCENE`, also sets the maximum number of clauses permitted per BooleanQuery. This is so that all enforced query limits @@ -3318,9 +3316,9 @@ Common examples: [[note-db]] === Section noteDb -NoteDb is the next generation of Gerrit storage backend, currently powering -`googlesource.com`. For more information, including how to migrate your data, -see the link:note-db.html[documentation]. +NoteDb is the Git-based database storage backend for Gerrit. For more +information, including how to migrate data from an older Gerrit version, see the +link:note-db.html[documentation]. [[notedb.accounts.sequenceBatchSize]]notedb.accounts.sequenceBatchSize:: + diff --git a/Documentation/config-robot-comments.txt b/Documentation/config-robot-comments.txt index cf5de1012c..00776972b3 100644 --- a/Documentation/config-robot-comments.txt +++ b/Documentation/config-robot-comments.txt @@ -36,7 +36,6 @@ Robot comments can be dropped by deleting this ref. == Limitations -* Robot comments are only supported with NoteDb, but not with ReviewDb. * Robot comments are not displayed in the web UI yet. * There is no support for draft robot comments, but robot comments are always published and visible to everyone who can see the change. diff --git a/Documentation/dev-contributing.txt b/Documentation/dev-contributing.txt index 6dce1e619c..3b1c501dd7 100644 --- a/Documentation/dev-contributing.txt +++ b/Documentation/dev-contributing.txt @@ -250,7 +250,6 @@ back and consult this section when creating them. Here are some design level objectives that you should keep in mind when coding: - * ORM entity objects should match exactly one row in the database. * Most client pages should perform only one RPC to load so as to keep latencies down. Exceptions would apply to RPCs which need to load large data sets if splitting them out will help the @@ -269,10 +268,11 @@ when coding: * Don't leave repository objects (git or schema) open. A .close() after every open should be placed in a finally{} block. * Don't leave UI components, which can cause new actions to occur, - enabled during RPCs which update the DB. This is to prevent - people from submitting actions more than once when operating - on slow links. If the action buttons are disabled, they cannot - be resubmitted and the user can see that Gerrit is still busy. + enabled during RPCs which update Git repositories, including NoteDb. + This is to prevent people from submitting actions more than once + when operating on slow links. If the action buttons are disabled, + they cannot be resubmitted and the user can see that Gerrit is still + busy. * ...and so is Guava (previously known as Google Collections). diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt index e84effd5dd..f2bd273ea3 100644 --- a/Documentation/dev-plugins.txt +++ b/Documentation/dev-plugins.txt @@ -325,10 +325,10 @@ from the Section.Factory rather than from an injected Config object. Plugins' InitSteps are executed during the "Gerrit Plugin init" phase, after the extraction of the plugins embedded in the distribution .war file into -`$GERRIT_SITE/plugins` and before the DB Schema initialization or upgrade. +`$GERRIT_SITE/plugins` and before the site initialization or upgrade. -A plugin's InitStep cannot refer to Gerrit's DB Schema or any other Gerrit -runtime objects injected at startup. +A plugin's InitStep cannot refer to any Gerrit runtime objects injected at +startup. [source,java] ---- @@ -1573,9 +1573,8 @@ public Object apply(RevisionResource rcrs, Input in) { // schedule a build [...] // update change - ReviewDb db = dbProvider.get(); try (BatchUpdate bu = batchUpdateFactory.create( - db, project.getNameKey(), user, TimeUtil.nowTs())) { + project.getNameKey(), user, TimeUtil.nowTs())) { bu.addOp(change.getId(), new BatchUpdate.Op() { @Override public boolean updateChange(ChangeContext ctx) { diff --git a/Documentation/install.txt b/Documentation/install.txt index be554172af..0885da1a29 100644 --- a/Documentation/install.txt +++ b/Documentation/install.txt @@ -61,8 +61,7 @@ the notes under link:dev-readme.html[developer setup]. Gerrit stores configuration files, the server's SSH keys, and the managed Git repositories under a local directory, typically referred -to as `'$site_path'`. If the embedded H2 database is being used, -its data files will also be stored under this directory. +to as `'$site_path'`. You also have to decide where to store your server side git repositories. This can either be a relative path under `'$site_path'` or an absolute path @@ -87,11 +86,10 @@ have any privileges, you may have to manually create the directory first and then give ownership of that location to the `'gerrit'` user. If run from an interactive terminal, the init command will prompt through a -series of configuration questions, including gathering information -about the database created above. If the terminal is not interactive, -running the init command will choose some reasonable default selections, -and will use the embedded H2 database. Once the init phase is complete, -you can review your settings in the file `'$site_path/etc/gerrit.config'`. +series of configuration questions. If the terminal is not interactive, +running the init command will choose some reasonable default selections. +Once the init phase is complete, you can review your settings in the file +`'$site_path/etc/gerrit.config'`. When running the init command, additional JARs might be downloaded to support optional selected functionality. If a download fails a URL will diff --git a/Documentation/metrics.txt b/Documentation/metrics.txt index ced4609448..6864c685a9 100644 --- a/Documentation/metrics.txt +++ b/Documentation/metrics.txt @@ -106,10 +106,6 @@ Each queue provides the following metrics: * `sshd/sessions/created`: Rate of new SSH sessions. * `sshd/sessions/authentication_failures`: Rate of SSH authentication failures. -=== SQL connections - -* `sql/connection_pool/connections`: SQL database connections. - === Topics * `topic/cross_project_submit`: number of cross-project topic submissions. diff --git a/Documentation/pgm-LocalUsernamesToLowerCase.txt b/Documentation/pgm-LocalUsernamesToLowerCase.txt index 4b50961893..53081a18ba 100644 --- a/Documentation/pgm-LocalUsernamesToLowerCase.txt +++ b/Documentation/pgm-LocalUsernamesToLowerCase.txt @@ -47,7 +47,7 @@ it must be run by itself. == CONTEXT This command can only be run on a server which has direct -connectivity to the metadata database. +connectivity to the managed Git repositories. == EXAMPLES To convert the local username of every account to lower case: diff --git a/Documentation/pgm-init.txt b/Documentation/pgm-init.txt index 9a16cdfa13..f6c3c85d3e 100644 --- a/Documentation/pgm-init.txt +++ b/Documentation/pgm-init.txt @@ -28,7 +28,7 @@ for some basic setup prior to writing default configuration files into a newly created `$site_path`. If run in an existing `$site_path`, init upgrades existing resources -(e.g. DB schema, plugins) as necessary. +(e.g. NoteDb schema, plugins) as necessary. == OPTIONS -b:: @@ -100,8 +100,7 @@ objects these SQL statements must be executed manually. folder. == CONTEXT -This command can only be run on a server which has direct -connectivity to the metadata database, and local access to the +This command can only be run on a server which has direct local access to the managed Git repositories. GERRIT diff --git a/Documentation/pgm-rulec.txt b/Documentation/pgm-rulec.txt index 1b50812aaa..2a987205ac 100644 --- a/Documentation/pgm-rulec.txt +++ b/Documentation/pgm-rulec.txt @@ -33,8 +33,7 @@ named `rules-'SHA1'.jar` in `'$site_path'/cache/rules`. Compile rules for the specified project. == CONTEXT -This command can only be run on a server which has direct -connectivity to the metadata database, and local access to the +This command can only be run on a server which has local access to the managed Git repositories. Caching needs to be enabled. See diff --git a/Documentation/user-upload.txt b/Documentation/user-upload.txt index 751e886a25..56602e27be 100644 --- a/Documentation/user-upload.txt +++ b/Documentation/user-upload.txt @@ -732,7 +732,7 @@ client invoked by the end-user, or by `repo upload`. This allows Gerrit to provide magical refs, such as `+refs/for/*+` for new change submission and `+refs/changes/*+` for change replacement. When a push request is received to create a ref in one of these -namespaces Gerrit performs its own logic to update the database, +namespaces Gerrit performs its own logic to update the review metadata, and then lies to the client about the result of the operation. A successful result causes the client to believe that Gerrit has created the ref, but in reality Gerrit hasn't created the ref at all.