Documentation/gerrit1-import.txt

Gerrit2 - Importing From Gerrit1
================================

To switch from Google App Engine running Gerrit1 to a Gerrit2 based
system, you need to export all of the data from the GAE data store
and load it into PostgreSQL, converting the schema in the process.

[NOTE]
You must be using a source build of both Gerrit1 and Gerrit2.
The Gerrit2 binary packages do not include the conversion tools
necessary to upgrade from Gerrit1.

[NOTE]
To get a source build of Gerrit1, use the version immediately before
it merged into Gerrit2: `git checkout v2.0-rc0^2`


GAE Backup
----------

Create a PostgreSQL database to house the backup:

====
  createdb -E UTF-8 gaeback
====

From the Gerrit1 sources, load the schema:

====
  psql -f backup/create.sql gaeback
====

Ensure you have a copy of the Google App Engine SDK in
`../../google_appengine`.  This path is hardcoded into the backup
script.  (Or edit the backup script to import the SDK directory.)

Execute the backup task, supplying the credentials of
an application developer:

====
  webapp/backup_gae.py \
-d gaeback \
-s yourapp.appspot.com \
-e you@example.com
====

Backups are not incremental, they dump the entire data store.
The backup does not clear the database.  If you are doing
repeated conversions, it is recommended that you use `dropdb`
to drop the database and recreate it before each backup.

Backups are not consistent.  You may want to consider uploading the
application in administrator-only mode, so end-users cannot modify
the data store while the backup is taking place:

====
  make update APPID=yourapp ADMIN_ONLY=1
====

To restore normal access:

====
  make update APPID=yourapp
====

Export Dump File
----------------

Rename the schema to `gerrit1`, and then dump it into a
backup file:

====
  psql -c 'ALTER SCHEMA public RENAME TO gerrit1' gaeback
  pg_dump -O -Fc gaeback >yourapp.dump
====

Gerrit2 Database Setup
----------------------

Tell Gerrit about your database connection information.  Note that
the username you use here *must* be the default of `gerrit2` and
the database name *must* be the default of `reviewdb`, unless you
modify `gerrit1_import/1-to-2.sh`.

====
  ./gerrit.war --cat extra/GerritServer.properties_example >GerritServer.properties
====

Make sure the user exists in PostgreSQL:

====
  createuser -A -D -P -E gerrit2
====

Gerrit2 Import
--------------

Create a short SQL script to set the `system_config` table correctly
for the import process.  This might look like:

====
  $ cat config.sql
  UPDATE system_config
  SET git_base_path='/srv/git';
====

where `git_base_path` is pointing to the same directory that
`codereview.basedir` was set to in your Gerrit1 mgrapp config file.
The import task requires read access to these repositories.

In the Gerrit2 source tree use `1-to-2.sh` to finish the conversion
process:

====
  sh gerrit1_import/1-to-2.sh yourapp.dump config.sql
====


Fixup Groups
------------

During the Gerrit1 to Gerrit2 schema conversion process some
additional groups may have been created.  This was necessary
to enforce the same permissions within a project while moving
to a system that assigns permissions only to groups, and not
to individual users.

You may want to browse #admin,groups once logged in through
the web UI and cleanup any group names that were generated
automatically by the import process.


User Account Migration
----------------------

After import `system_config.allow_google_account_upgrade` will be
set to `Y` to permit users to upgrade their account from a Google
Account in Google App Engine to an OpenID based Google Account.

Its strongly encouraged for administrators to set this flag to 'N'
once the following query drops to 0, or close to 0:

====
  SELECT COUNT(*) FROM account_external_ids e
  WHERE e.external_id LIKE 'Google Account %'
  AND NOT EXISTS (SELECT 1
    FROM account_external_ids o
    WHERE o.account_id = e.account_id
	AND o.external_id LIKE '%.google.com%/id?id=%');
====

the above query lists all users who have not yet converted their
accounts to the OpenID authentication scheme.  Unfortunately the
conversion must be done by each individual user logging in, as the
OpenID token is per-user, and per-site.