Thread: Catalog version numbering added (committers READ THIS)
I have added a new feature that I suggested a few weeks ago (and didn't
get a lot of feedback about --- if you didn't like the idea, you shoulda
complained then ;-)). To wit, there is now an internal version number
that can be bumped anytime anyone makes an initdb-forcing change.
If we are faithful about changing this number when necessary, then
developers will not get burnt by failing to notice "you need to initdb"
messages in the pghackers list. I know some people have wasted hours
that way in the past.
The new number lives in src/include/catalog/catversion.h, and I think
I will just copy the comments in that file:
* catversion.h* "Catalog version number" for Postgres.** The catalog version number is used to flag incompatible
changesin* the Postgres system catalogs. Whenever anyone changes the format of* a system catalog relation, or adds,
deletes,or modifies standard* catalog entries in such a way that an updated backend wouldn't work* with an old database
(orvice versa), the catalog version number* should be changed. The version number stored in pg_control by initdb* is
checkedagainst the version number compiled into the backend at* startup time, so that a backend can refuse to run in an
incompatible*database.** The point of this feature is to provide a finer grain of compatibility* checking than is
possiblefrom looking at the major version number* stored in PG_VERSION. It shouldn't matter to end users, but during*
developmentcycles we usually make quite a few incompatible changes* to the contents of the system catalogs, and we
don'twant to bump the* major version number for each one. What we can do instead is bump* this internal version
number. This should save some grief for* developers who might otherwise waste time tracking down "bugs" that* are
reallyjust code-vs-database incompatibilities.** The rule for developers is: if you commit a change that requires* an
initdb,you should update the catalog version number (as well as* notifying the pghackers mailing list, which has been
theinformal* practice for a long time).** The catalog version number is placed here since modifying files in*
include/catalogis the most common kind of initdb-forcing change.* But it could be used to protect any kind of
incompatiblechange in* database contents or layout, such as altering tuple headers.
Naturally, you need to initdb after retrieving this update, but the
system will now tell you so if you forget! For example:
FATAL 2: database was initialized with CATALOG_VERSION_NO 0, but the backend was compiled with
CATALOG_VERSION_NO199910241. looks like you need to initdb.
regards, tom lane
Tom Lane wrote: > > Naturally, you need to initdb after retrieving this update, but the > system will now tell you so if you forget! For example: > > FATAL 2: database was initialized with CATALOG_VERSION_NO 0, > but the backend was compiled with CATALOG_VERSION_NO 199910241. > looks like you need to initdb. > > regards, tom lane Will the backend really tell me "regards, tom lane" ;) ---------- Hannu
Good idea. > I have added a new feature that I suggested a few weeks ago (and didn't > get a lot of feedback about --- if you didn't like the idea, you shoulda > complained then ;-)). To wit, there is now an internal version number > that can be bumped anytime anyone makes an initdb-forcing change. > > If we are faithful about changing this number when necessary, then > developers will not get burnt by failing to notice "you need to initdb" > messages in the pghackers list. I know some people have wasted hours > that way in the past. > > The new number lives in src/include/catalog/catversion.h, and I think > I will just copy the comments in that file: > > * catversion.h > * "Catalog version number" for Postgres. > * > * The catalog version number is used to flag incompatible changes in > * the Postgres system catalogs. Whenever anyone changes the format of > * a system catalog relation, or adds, deletes, or modifies standard > * catalog entries in such a way that an updated backend wouldn't work > * with an old database (or vice versa), the catalog version number > * should be changed. The version number stored in pg_control by initdb > * is checked against the version number compiled into the backend at > * startup time, so that a backend can refuse to run in an incompatible > * database. > * > * The point of this feature is to provide a finer grain of compatibility > * checking than is possible from looking at the major version number > * stored in PG_VERSION. It shouldn't matter to end users, but during > * development cycles we usually make quite a few incompatible changes > * to the contents of the system catalogs, and we don't want to bump the > * major version number for each one. What we can do instead is bump > * this internal version number. This should save some grief for > * developers who might otherwise waste time tracking down "bugs" that > * are really just code-vs-database incompatibilities. > * > * The rule for developers is: if you commit a change that requires > * an initdb, you should update the catalog version number (as well as > * notifying the pghackers mailing list, which has been the informal > * practice for a long time). > * > * The catalog version number is placed here since modifying files in > * include/catalog is the most common kind of initdb-forcing change. > * But it could be used to protect any kind of incompatible change in > * database contents or layout, such as altering tuple headers. > > Naturally, you need to initdb after retrieving this update, but the > system will now tell you so if you forget! For example: > > FATAL 2: database was initialized with CATALOG_VERSION_NO 0, > but the backend was compiled with CATALOG_VERSION_NO 199910241. > looks like you need to initdb. > > regards, tom lane > > ************ > -- Bruce Momjian | http://www.op.net/~candle maillist@candle.pha.pa.us | (610) 853-3000+ If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania19026