04995967e2
git-svn-id: svn://10.0.0.236/branches/BUGZILLA-2_16-BRANCH@121345 18797224-902f-48f8-a5cc-f745e15eee43
516 lines
28 KiB
HTML
516 lines
28 KiB
HTML
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>MySQL Bugzilla Database Introduction</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
|
"><LINK
|
|
REL="HOME"
|
|
TITLE="The Bugzilla Guide"
|
|
HREF="index.html"><LINK
|
|
REL="UP"
|
|
TITLE="The Bugzilla Database"
|
|
HREF="database.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Database Schema Chart"
|
|
HREF="dbschema.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="MySQL Permissions & Grant Tables"
|
|
HREF="granttables.html"></HEAD
|
|
><BODY
|
|
CLASS="section"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>The Bugzilla Guide</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="dbschema.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
>Appendix B. The Bugzilla Database</TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="granttables.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H1
|
|
CLASS="section"
|
|
><A
|
|
NAME="dbdoc">B.2. MySQL Bugzilla Database Introduction</H1
|
|
><P
|
|
>This information comes straight from my life. I was forced to learn
|
|
how Bugzilla organizes database because of nitpicky requests from users
|
|
for tiny changes in wording, rather than having people re-educate
|
|
themselves or figure out how to work our procedures around the tool. It
|
|
sucks, but it can and will happen to you, so learn how the schema works
|
|
and deal with it when it comes.</P
|
|
><P
|
|
>So, here you are with your brand-new installation of Bugzilla.
|
|
You've got MySQL set up, Apache working right, Perl DBI and DBD talking
|
|
to the database flawlessly. Maybe you've even entered a few test bugs to
|
|
make sure email's working; people seem to be notified of new bugs and
|
|
changes, and you can enter and edit bugs to your heart's content. Perhaps
|
|
you've gone through the trouble of setting up a gateway for people to
|
|
submit bugs to your database via email, have had a few people test it,
|
|
and received rave reviews from your beta testers.</P
|
|
><P
|
|
>What's the next thing you do? Outline a training strategy for your
|
|
development team, of course, and bring them up to speed on the new tool
|
|
you've labored over for hours.</P
|
|
><P
|
|
>Your first training session starts off very well! You have a
|
|
captive audience which seems enraptured by the efficiency embodied in
|
|
this thing called "Bugzilla". You are caught up describing the nifty
|
|
features, how people can save favorite queries in the database, set them
|
|
up as headers and footers on their pages, customize their layouts,
|
|
generate reports, track status with greater efficiency than ever before,
|
|
leap tall buildings with a single bound and rescue Jane from the clutches
|
|
of Certain Death!</P
|
|
><P
|
|
>But Certain Death speaks up -- a tiny voice, from the dark corners
|
|
of the conference room. "I have a concern," the voice hisses from the
|
|
darkness, "about the use of the word 'verified'.</P
|
|
><P
|
|
>The room, previously filled with happy chatter, lapses into
|
|
reverential silence as Certain Death (better known as the Vice President
|
|
of Software Engineering) continues. "You see, for two years we've used
|
|
the word 'verified' to indicate that a developer or quality assurance
|
|
engineer has confirmed that, in fact, a bug is valid. I don't want to
|
|
lose two years of training to a new software product. You need to change
|
|
the bug status of 'verified' to 'approved' as soon as possible. To avoid
|
|
confusion, of course."</P
|
|
><P
|
|
>Oh no! Terror strikes your heart, as you find yourself mumbling
|
|
"yes, yes, I don't think that would be a problem," You review the changes
|
|
with Certain Death, and continue to jabber on, "no, it's not too big a
|
|
change. I mean, we have the source code, right? You know, 'Use the
|
|
Source, Luke' and all that... no problem," All the while you quiver
|
|
inside like a beached jellyfish bubbling, burbling, and boiling on a hot
|
|
Jamaican sand dune...</P
|
|
><P
|
|
>Thus begins your adventure into the heart of Bugzilla. You've been
|
|
forced to learn about non-portable enum() fields, varchar columns, and
|
|
tinyint definitions. The Adventure Awaits You!</P
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="AEN2146">B.2.1. Bugzilla Database Basics</H2
|
|
><P
|
|
>If you were like me, at this point you're totally clueless about
|
|
the internals of MySQL, and if it weren't for this executive order from
|
|
the Vice President you couldn't care less about the difference between
|
|
a
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>"bigint"</SPAN
|
|
>
|
|
|
|
and a
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>"tinyint"</SPAN
|
|
>
|
|
|
|
entry in MySQL. I recommend you refer to the MySQL documentation,
|
|
available at
|
|
<A
|
|
HREF="http://www.mysql.com/doc.html"
|
|
TARGET="_top"
|
|
>MySQL.com</A
|
|
>
|
|
|
|
. Below are the basics you need to know about the Bugzilla database.
|
|
Check the chart above for more details.</P
|
|
><P
|
|
> <P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
>To connect to your database:</P
|
|
><P
|
|
> <TT
|
|
CLASS="prompt"
|
|
>bash#</TT
|
|
>
|
|
|
|
<B
|
|
CLASS="command"
|
|
>mysql</B
|
|
>
|
|
|
|
<TT
|
|
CLASS="parameter"
|
|
><I
|
|
>-u root</I
|
|
></TT
|
|
>
|
|
</P
|
|
><P
|
|
>If this works without asking you for a password,
|
|
<EM
|
|
>shame on you</EM
|
|
>
|
|
|
|
! You should have locked your security down like the installation
|
|
instructions told you to. You can find details on locking down
|
|
your database in the Bugzilla FAQ in this directory (under
|
|
"Security"), or more robust security generalities in the MySQL
|
|
searchable documentation at
|
|
http://www.mysql.com/php/manual.php3?section=Privilege_system
|
|
.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>You should now be at a prompt that looks like this:</P
|
|
><P
|
|
> <TT
|
|
CLASS="prompt"
|
|
>mysql></TT
|
|
>
|
|
</P
|
|
><P
|
|
>At the prompt, if
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>"bugs"</SPAN
|
|
>
|
|
|
|
is the name you chose in the
|
|
<TT
|
|
CLASS="filename"
|
|
>localconfig</TT
|
|
>
|
|
|
|
file for your Bugzilla database, type:</P
|
|
><P
|
|
> <TT
|
|
CLASS="prompt"
|
|
>mysql</TT
|
|
>
|
|
|
|
<B
|
|
CLASS="command"
|
|
>use bugs;</B
|
|
>
|
|
</P
|
|
><DIV
|
|
CLASS="note"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="note"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/note.gif"
|
|
HSPACE="5"
|
|
ALT="Note"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>Don't forget the
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>";"</SPAN
|
|
>
|
|
|
|
at the end of each line, or you'll be kicking yourself
|
|
later.</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></LI
|
|
></OL
|
|
>
|
|
</P
|
|
><DIV
|
|
CLASS="section"
|
|
><H3
|
|
CLASS="section"
|
|
><A
|
|
NAME="AEN2175">B.2.1.1. Bugzilla Database Tables</H3
|
|
><P
|
|
>Imagine your MySQL database as a series of spreadsheets, and
|
|
you won't be too far off. If you use this command:</P
|
|
><P
|
|
> <TT
|
|
CLASS="prompt"
|
|
>mysql></TT
|
|
>
|
|
|
|
<B
|
|
CLASS="command"
|
|
>show tables from bugs;</B
|
|
>
|
|
</P
|
|
><P
|
|
>you'll be able to see all the
|
|
<SPAN
|
|
CLASS="QUOTE"
|
|
>"spreadsheets"</SPAN
|
|
>
|
|
|
|
(tables) in your database. It is similar to a file system, only
|
|
faster and more robust for certain types of operations.</P
|
|
><P
|
|
>From the command issued above, ou should have some output that
|
|
looks like this:
|
|
<TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
>+-------------------+ | Tables in bugs |
|
|
+-------------------+ | attachments | | bugs | | bugs_activity | | cc
|
|
| | components | | dependencies | | fielddefs | | groups | |
|
|
keyworddefs | | keywords | | logincookies | | longdescs | |
|
|
milestones | | namedqueries | | products | | profiles | |
|
|
profiles_activity | | shadowlog | | tokens | | versions | | votes | |
|
|
watch | +-------------------+</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
>
|
|
</P
|
|
><P
|
|
CLASS="literallayout"
|
|
>Here's an overview of what each table does. Most<br>
|
|
columns in each table have descriptive names that make it fairly<br>
|
|
trivial to figure out their jobs. attachments: This table stores all<br>
|
|
attachments to bugs. It tends to be your largest table, yet also<br>
|
|
generally has the fewest entries because file attachments are so<br>
|
|
(relatively) large. bugs: This is the core of your system. The bugs<br>
|
|
table stores most of the current information about a bug, with the<br>
|
|
exception of the info stored in the other tables. bugs_activity: This<br>
|
|
stores information regarding what changes are made to bugs when -- a<br>
|
|
history file. cc: This tiny table simply stores all the CC<br>
|
|
information for any bug which has any entries in the CC field of the<br>
|
|
bug. Note that, like most other tables in Bugzilla, it does not refer<br>
|
|
to users by their user names, but by their unique userid, stored as a<br>
|
|
primary key in the profiles table. components: This stores the<br>
|
|
programs and components (or products and components, in newer<br>
|
|
Bugzilla parlance) for Bugzilla. Curiously, the "program" (product)<br>
|
|
field is the full name of the product, rather than some other unique<br>
|
|
identifier, like bug_id and user_id are elsewhere in the database.<br>
|
|
dependencies: Stores data about those cool dependency trees.<br>
|
|
fielddefs: A nifty table that defines other tables. For instance,<br>
|
|
when you submit a form that changes the value of "AssignedTo" this<br>
|
|
table allows translation to the actual field name "assigned_to" for<br>
|
|
entry into MySQL. groups: defines bitmasks for groups. A bitmask is a<br>
|
|
number that can uniquely identify group memberships. For instance,<br>
|
|
say the group that is allowed to tweak parameters is assigned a value<br>
|
|
of "1", the group that is allowed to edit users is assigned a "2",<br>
|
|
and the group that is allowed to create new groups is assigned the<br>
|
|
bitmask of "4". By uniquely combining the group bitmasks (much like<br>
|
|
the chmod command in UNIX,) you can identify a user is allowed to<br>
|
|
tweak parameters and create groups, but not edit users, by giving him<br>
|
|
a bitmask of "5", or a user allowed to edit users and create groups,<br>
|
|
but not tweak parameters, by giving him a bitmask of "6" Simple, huh?<br>
|
|
If this makes no sense to you, try this at the mysql prompt:<br>
|
|
mysql> select * from groups; You'll see the list, it makes much<br>
|
|
more sense that way. keyworddefs: Definitions of keywords to be used<br>
|
|
keywords: Unlike what you'd think, this table holds which keywords<br>
|
|
are associated with which bug id's. logincookies: This stores every<br>
|
|
login cookie ever assigned to you for every machine you've ever<br>
|
|
logged into Bugzilla from. Curiously, it never does any housecleaning<br>
|
|
-- I see cookies in this file I've not used for months. However,<br>
|
|
since Bugzilla never expires your cookie (for convenience' sake), it<br>
|
|
makes sense. longdescs: The meat of bugzilla -- here is where all<br>
|
|
user comments are stored! You've only got 2^24 bytes per comment<br>
|
|
(it's a mediumtext field), so speak sparingly -- that's only the<br>
|
|
amount of space the Old Testament from the Bible would take<br>
|
|
(uncompressed, 16 megabytes). Each comment is keyed to the bug_id to<br>
|
|
which it's attached, so the order is necessarily chronological, for<br>
|
|
comments are played back in the order in which they are received.<br>
|
|
milestones: Interesting that milestones are associated with a<br>
|
|
specific product in this table, but Bugzilla does not yet support<br>
|
|
differing milestones by product through the standard configuration<br>
|
|
interfaces. namedqueries: This is where everybody stores their<br>
|
|
"custom queries". Very cool feature; it beats the tar out of having<br>
|
|
to bookmark each cool query you construct. products: What products<br>
|
|
you have, whether new bug entries are allowed for the product, what<br>
|
|
milestone you're working toward on that product, votes, etc. It will<br>
|
|
be nice when the components table supports these same features, so<br>
|
|
you could close a particular component for bug entry without having<br>
|
|
to close an entire product... profiles: Ahh, so you were wondering<br>
|
|
where your precious user information was stored? Here it is! With the<br>
|
|
passwords in plain text for all to see! (but sshh... don't tell your<br>
|
|
users!) profiles_activity: Need to know who did what when to who's<br>
|
|
profile? This'll tell you, it's a pretty complete history. shadowlog:<br>
|
|
I could be mistaken here, but I believe this table tells you when<br>
|
|
your shadow database is updated and what commands were used to update<br>
|
|
it. We don't use a shadow database at our site yet, so it's pretty<br>
|
|
empty for us. versions: Version information for every product votes:<br>
|
|
Who voted for what when watch: Who (according to userid) is watching<br>
|
|
who's bugs (according to their userid). === THE DETAILS === Ahh, so<br>
|
|
you're wondering just what to do with the information above? At the<br>
|
|
mysql prompt, you can view any information about the columns in a<br>
|
|
table with this command (where "table" is the name of the table you<br>
|
|
wish to view): mysql> show columns from table; You can also view<br>
|
|
all the data in a table with this command: mysql> select * from<br>
|
|
table; -- note: this is a very bad idea to do on, for instance, the<br>
|
|
"bugs" table if you have 50,000 bugs. You'll be sitting there a while<br>
|
|
until you ctrl-c or 50,000 bugs play across your screen. You can<br>
|
|
limit the display from above a little with the command, where<br>
|
|
"column" is the name of the column for which you wish to restrict<br>
|
|
information: mysql> select * from table where (column = "some<br>
|
|
info"); -- or the reverse of this mysql> select * from table where<br>
|
|
(column != "some info"); Let's take our example from the<br>
|
|
introduction, and assume you need to change the word "verified" to<br>
|
|
"approved" in the resolution field. We know from the above<br>
|
|
information that the resolution is likely to be stored in the "bugs"<br>
|
|
table. Note we'll need to change a little perl code as well as this<br>
|
|
database change, but I won't plunge into that in this document. Let's<br>
|
|
verify the information is stored in the "bugs" table: mysql> show<br>
|
|
columns from bugs (exceedingly long output truncated here) |<br>
|
|
bug_status|<br>
|
|
enum('UNCONFIRMED','NEW','ASSIGNED','REOPENED','RESOLVED','VERIFIED','CLOSED')||MUL<br>
|
|
| UNCONFIRMED|| Sorry about that long line. We see from this that the<br>
|
|
"bug status" column is an "enum field", which is a MySQL peculiarity<br>
|
|
where a string type field can only have certain types of entries.<br>
|
|
While I think this is very cool, it's not standard SQL. Anyway, we<br>
|
|
need to add the possible enum field entry 'APPROVED' by altering the<br>
|
|
"bugs" table. mysql> ALTER table bugs CHANGE bug_status bug_status<br>
|
|
-> enum("UNCONFIRMED", "NEW", "ASSIGNED", "REOPENED", "RESOLVED",<br>
|
|
-> "VERIFIED", "APPROVED", "CLOSED") not null; (note we can take<br>
|
|
three lines or more -- whatever you put in before the semicolon is<br>
|
|
evaluated as a single expression) Now if you do this: mysql> show<br>
|
|
columns from bugs; you'll see that the bug_status field has an extra<br>
|
|
"APPROVED" enum that's available! Cool thing, too, is that this is<br>
|
|
reflected on your query page as well -- you can query by the new<br>
|
|
status. But how's it fit into the existing scheme of things? Looks<br>
|
|
like you need to go back and look for instances of the word<br>
|
|
"verified" in the perl code for Bugzilla -- wherever you find<br>
|
|
"verified", change it to "approved" and you're in business (make sure<br>
|
|
that's a case-insensitive search). Although you can query by the enum<br>
|
|
field, you can't give something a status of "APPROVED" until you make<br>
|
|
the perl changes. Note that this change I mentioned can also be done<br>
|
|
by editing checksetup.pl, which automates a lot of this. But you need<br>
|
|
to know this stuff anyway, right? I hope this database tutorial has<br>
|
|
been useful for you. If you have comments to add, questions,<br>
|
|
concerns, etc. please direct them to mbarnson@excitehome.net. Please<br>
|
|
direct flames to /dev/null :) Have a nice day! === LINKS === Great<br>
|
|
MySQL tutorial site:<br>
|
|
http://www.devshed.com/Server_Side/MySQL/</P
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="dbschema.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="granttables.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Database Schema Chart</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="database.html"
|
|
ACCESSKEY="U"
|
|
>Up</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>MySQL Permissions & Grant Tables</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |