Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Derby Development" <derby-dev@db.apache.org>
Message-ID: <412E31EB.4090302@debrunners.com>
Date: Thu, 26 Aug 2004 11:54:35 -0700
From: Daniel John Debrunner <djd@debrunners.com>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.4.1) Gecko/20031008
MIME-Version: 1.0
To: Derby Development <derby-dev@db.apache.org>
Subject: Re: version scheme
References: <412E278B.5070109@debrunners.com>
In-Reply-To: <412E278B.5070109@debrunners.com>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

This is a description of how the mechanics of the code is set up to
handle upgrade and how it was intended to work for Cloudscape. Now as
Derby there are no guarantees at the moment that the project will
continue using this scheme.

Dan.

| Externally the code uses a four part version number
|
| ~  Minor.major.fixpack.point  or M.m.f.p

The database engine has a version EM.Em.Ef.Ep.

An on disk database has a persistent current version that corresponds to
the engine that created it, or last upgraded it, DM.Dm.Df.Dp.

The general rules for Cloudscape were (and are in the Derby code)

For a on-disk database at version DM.Dm.Df.Dp

1) Any engine with EM == DM and Em == Dm can be used.

2) Any engine with EM.Em < DM.Dm will not boot the database.

3) Any engine with EM.Em > DM.Dm will boot the database in soft upgrade
mode.

4) Any engine with EM.Em > DM.DM can boot and upgrade the database to
its own version (EM.Em.Ef.Ep).

5) Exception that any database created by an alpha or beta engine can
not be upgraded or run in soft upgrade mode.

6) Exception that any alpha or beta engine may not run in soft upgrade
mode or perform an upgrade.

7) Requirement that EM >= 10 and DM >= 10.


Soft upgrade is a mode where a newer engine can run against an older
database successfully, but does not support any of the engine's new
features that would not be understood by an engine at the database's
version of DM.Dm. An exception is thrown if such a feature is used.
The idea here is to allow a single version of the engine in a JVM be
upgraded without requiring all databases be upgraded. Soft upgrade may
make changes to the on-disk database that can be safely consumed by
older releases, e.g. fix incorrect system catalog entries.

Upgrade is enabled by the boot connection to the database using the
upgrade=true attribute. This modifies the on-disk form of the database
by making any required changes, such as adding a new system catalog to
support some new SQL feature. Once a database is upgraded, it cannot be
downgraded.

Example (all version numbers are made up, only the inital code at
10.0.2.0 exists at the moment)

Database SALESDB created by 10.0.2.4 engine.

Any 10.0.x.y engine can now run successfully against SALESDB, e.g.
application can use 10.0.2.8, 10.0.4.23, revert to 10.0.2.0 with no issues.

A future 10.2.0.0 (alpha) release would not boot SALESDB as it is an
alpha release.

A future 10.2.1.3 (beta) release would not boot SALESDB as it is an beta
release.

A future 10.2.2.3 release would boot SALESDB in soft upgrade mode. If
say 10.2.2.3 had added GRANT/REVOKE, then any attempt to use those SQL
statements would result in an exception indicating the database must be
upgraded to 10.2. Also any new features added in 10.1 would throw an
exception indicating the database must be upgraded to 10.1.

Connecting to SALESDB with 10.2.2.3 with the attribute upgrade=true
would upgrade the database to 10.2.2.3. Subsquently any attempt to boot
SALESDB with 10.0.x.y or 10.1.x.y would fail.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFBLjHqIv0S4qsbfuQRAqlcAJ0XT9N7C+gR0hIQ5rRYkWwwADj5cACcCjlg
/w4Kgi+InEL7fb8SCuyFvCs=
=BT05
-----END PGP SIGNATURE-----