Planet MCslp

Reorganizing the documentation

Those of you that know the documentation well will be aware of the old page we used to have for the MySQL documentation. It was huge, and over the years we’d done a number of things to try and improve the layout and make it easier to find what you wanted. We had in-age links to jump to the different documentation types, and the old topic table that allowed you to jump to specific parts of the documentation.

The problem was that the more documentation that we produced (and there are over a thousand docs in various formats now), the bigger the page got. When we added the individual topic guides, for example, we trebled the size of the page by adding the links for each individual topic guide.

Ultimately that makes it increasingly difficult for you guys to find what you are looking for, despite the quick links and other elements.

We’ve now changed all this and split the single, big, monolithic page of *every* piece of documentation that we create, and instead spread the documentation out over a number of pages. The actual documentation itself remains the same, and we still have the same range of documentation (in fact, it’s increased slightly as I’ve been able to squeeze in a few more formats and topic guide docs), but everything is still there.

The key is the new sub-navigation bar that the Web team have provided us with:

The pages have been split out as follows:

• MySQL Manual — the full, complete reference manuals
• Workbench — the Workbench manuals
• Expert Guides — the standalone guides for some of our more detailed products and system such as the Falcon storage engine and the MySQL Test Framework
• Topic Guides — the topic reference, with the topic table at the top providing direct links into the 5.1 manual or standalone guides, and the full list of downloadable standalone guides.
• MySQL Cluster — the full cluster manuals, including the guide to the MySQL Cluster API (NDBAPI)
• Other docs — other documentation, not already mentioned, including the sample databases (Sakila, World, Employee), the help tables you can import into MySQL, and printed material and links elsewhere.
• MySQL Uni — a page about the MySQL University, which is run by the documentation team, and which provides links to the MySQL Uni pages on Forge
• About — information about the documentation team, who we are, and some statistics on the documentation we produce
• Archives — archives of older manuals

We are aware of a few issues with some of the links to some documentation, and I’m working right now to address those problems, but all the documentation should be there and available. If it isn’t, please report a Bug.

Adding Workflows to the Installation Guides

One of the elements that I have wanted to add to the installation chapter for some time has been some flowcharts to make understanding the steps required to successfully complete an installation on various platforms.

The Windows one is the most interesting, because not only do we have the installer, but we also have the MySQL Server Instance Config Wizard which has its own sequence of steps to configure an instance of the server.

I’m still working out and refining the examples and the graphics, but here is an example of the config wizard output:

Hopefully the full suite of images will be in the documentation shortly – all comments and input welcome.

Rebuilding the installation chapter

Although we have lots of things on the go right now (over and above the normal process of keeping things up to date), and one of the main projects for me is to do a complete rebuild of the installation chapter (Installing and Upgrading MySQL). I’ll be starting with the 5.1 manual, then the 5.4 manuals. Any future manuals should be based on these so we should be up to date for future generations.

What I’m doing:

• Re-structuring the chapter to make it easier to follow on a platform basis. The old structure mixed content for different binary and source types, and different platforms, across a number of sections, making it very difficult to follow the instructions for your chosen platform.
• Make some things generic. There are sections which are generic and apply to all (or at least many) different installation types.
• Make some things more specific. Equally, there are some things that need to be spelled out more uniquely.
• Remove some old, old, advice. We have notes in there going back 10 years or more. Among the favorite examples I’ve found is a piece of advice that says ‘If your machine has more than 16MB of RAM…’. These things are not helpful in the manual, and may just serve to confuse some people.
• Remove some older platforms. Some of the platforms and advice go back and predate MySQL 5.1, and even MySQL 5.0 and 4.1. In many cases the OS information is for a system either no longer actively developed or supported (FreeBSD 3.x, or Solaris 2.5, for example). Again, we want to remove some ambiguous and potentially confusing information and advice here for platforms which we simply can no longer monitor.
• Make it easier to keep up date. The problem with the old organic structure is that knowing where to add new content, improvements, extensions, etc. becomes harder and harder. by merging and unifying the structure we will improve this, and in turn, improve the ability to find information.

In practice that means for at least the next month or so you will see a number of improvements and restructuring in the installation chapter for 5.1 and later manuals.

I already have a list of about 35 items that need to be addressed, over and above the list above, but feel free to provide any additional suggestions and I’ll see what I can do to fit them in.

YouTube ? Improving Performance by Running MySQL Multiple Times

Feels like a long time ago, but my talk at the MySQL User’s Conference back in April 09 on running MySQL Multiple Times to get better performance is now available online at YouTube. The original PDF of the presentation is available here.

View it here: YouTube – Improving Performance by Running MySQL Multiple Times

Dojo examples from UC2009

I know, I know, loads of people have been waiting for these…

So here we go, I’ve finally sorted a downloaded version of the Dojo examples from the presentation I provided at the MySQL Users Conference 2009.

There are three examples:

• The auto-paging table example, which uses the functionality of the Dojo Toolkit and the QueryReadStore to automatically load content from a table.
  
• The basic graphing example, which loads data dynamically and plots a graph.
  
• And the zooming version of the same basic graph interface

There’s a README in the download that contains instructions on getting everything up to speed, although it should be fairly obvious. It’s attached to the bottom of this post too.

Any questions for getting this to work, please go ahead and ask!

Download the package here


UC2009 Working with MySQL and Dojo
==================================

MC Brown, 2009, http://mcslp.com and http://coalface.mcslp.com

Components:

There are three examples here:

- Dojo table with auto-paging
(table_autopage.html and table_autopage.cgi)

- Dojo Basic Graph
(graph_basic.html and graph_ajax.cgi)

- Dojo Zooming Graph
(graph.html and graph_ajaz_zoom.cgi)

You will also need the Dojo/Dijit and DojoX toolkit package from here:

http://www.dojotoolkit.org/downloads

Download the combined package, and then extract the contents and place in the same directory as the CGI scripts

Intructions for use:

For the Table example, you can create a table (or use an existing DB) from Wordpress using the wp_posts tabls.

In practice you need only create and populate a table with the following columns:

id (int)
user_nicename (char)
post_date (datetime)
post_title (char)

To be compatible with the example without any more modifications.

For the Graphing examples, you need a table as follows:

CREATE TABLE `currencies` (
`currencyid` bigint(20) unsigned NOT NULL auto_increment,
`currency` char(20) default NULL,
`value` float default NULL,
`datetime` int(11) default NULL,
`new` int(11) default NULL,
PRIMARY KEY (`currencyid`),
UNIQUE KEY `currencyid` (`currencyid`),
KEY `currencies_currency` (`currency`,`datetime`),
KEY `currencies_datetime` (`datetime`)
) ENGINE=MyISAM AUTO_INCREMENT=170048 DEFAULT CHARSET=latin1

And then populate with date/value data according to the information you want to store.

Once done, make sure you change the database information in the CGI scripts to populate the information correctly during operation.

Improved Indices for MySQL Reference Manual

I continue to try and find new ways to make it easier for people to get into the right place in the documentation for the information you are looking for.

This week, I’ve added some experimental custom indexes. These use information from the ID mapping process that we use in lots of parts of the documentation to do some interesting stuff.

The indexes are an extension of the other areas where we already provide summaries (like the list of options/variables, or functions). These provide quick access into the definition of the function, but not a link to where that function might have been mentioned elsewhere in the documentation. With the indexes, we’ve extended that so that you can now see all of the places within the reference manual where we mention a specific function. This goes beyond the index (which relies on us adding specific tags), and just lists everywhere that we mention a specific option.

Currently we only provide the new indexes in the 5.1 manual, in all formats, including online, downloadable and PDFs. The new indexes are:

• Standard Index - this is a version of the standard index, but with some minor improvements and adding extended support for see also and deeper index links.
• C Function Index - indexes all of the C functions used in the libmysql and API.
• Command Index - index all of the commands (mysql, mysqladmin and so on). We are aware of a few aberrations in the index.
• Function Index - an index of all the SQL functions we support.
• INFORMATION_SCHEMA Index - points to all of the uses of the INFORMATION_SCHEMA
• Transaction Isolation Level Index - pointers to all the places we quote different isolation levels.
• JOIN Types Index - examples of the different join types supported in SQL statements.
• Operator Index - SQL operators.
• Option Index - options, both for the server, and client commands.
• Privileges Index - all the different privileges supported through the GRANT syntax.
• SQL Modes Index - where we quote different SQL modes.
• Status Variable Index - status variables
• Statement/Syntax Index - where we use or provide examples of different SQL syntax and statements.
• System Variable Index - pointers to all the different system variables.

I am of course inviting comments and input from people to find out how useful you guys find this information. Assuming nobody has any objections, we’ll start rolling it out to the other reference manuals and documents.

Are there any other types of information presented in an index that our readers would like to see?

If so, let me know!!

MySQL 5.1 in OpenSolaris

If you’ve attended just one of my recent talks, either at the UC, LOSUG or MySQL University, you should know that MySQL 5.1.30 will be in the next official drop of OpenSolaris.

In fact, you can find MySQL 5.1 in the current pre-release builds - I just download build 111 of the future 2009.06 release.

Key things about the new MySQL 5.1 in OpenSolaris:

1. Contains the set of DTRACE probes that also exists in MySQL 5.4 (see DTrace Documentation)
2. Like the 5.0, we have SMF integration, so you can start, stop, monitor and change some of the core configuration through SMF
3. Directory layout is similar to 5.0, with a version specific directory (/usr/mysql/5.1), and the two can coexist if you want to handle a migration from 5.0 to 5.1

To install MySQL 5.1, use the pkg tool to perform the installation. We’ve split the components into three packages:

1. SUNWmysql51 contains the server and client binaries, and associated scripts.
2. SUNWmysql51libs contains the client libraries, which you’ll need for all external (i.e. MySQL) tools, like DBD::mysql for Perl connectivity)
3. SUNWmysql51test contains the MySQL test suite

To install:

$ pfexec pkg install SUNWmysql51

Once installed, you can start MySQL server through SMF:

$ pfexec svcadm enable mysql:version_51

You can set properties, like the data directory, by using svccfg:

$ svccfg
svc:> select mysql:version_51
svc:/application/database/mysql:version_51> setprop mysql/data=/data0/mysql
svc:/application/database/mysql:version_51> setprop mysql/enable_64bit=1

Any questions, please ask!

Quick Access to CommunityOne Deep Dives

So the CommunityOne conference is coming soon, and earlier this week I finished up the final part of the MySQL/DTrace presentation and preparation so I’m all ready to go.

Want to come along? Get quick access to the Deep Dives:

MySQL Docs Updates and Stats

We got an interesting question on the documentation list the other day, which basically asked if we provided a service that listed changes to specific pages in the manual.

While I like the idea of such a service, the mechanics of making such a service work are very difficult. To start with, and to re-iterate something I have to explain again and again:

the MySQL documentation is rebuilt up to 10 times *every* day

We don’t have set schedules for when we release changes. We don’t bundle changes up and then produce a new reference manual on a set day of the month, or week. If I make a change to the documentation right now, there is every chance that you would see that change in the live docs at http://dev.mysql.com/doc within 3 hours, and for the PDF format, possibly even within the hour.

Yep, it happens that quickly. And that happens every day of the year – even at weekends and holidays.

It’s also worth pointing out some of the statistics of the documentation to help explain why such a system might be impractical, but not impossible.

Our current mysqldoc repo, in existence since we made the move to DocBook, has just hit revision 14955, which means over the last 3 years and 7 months, we’ve made on average 11.45 commits every single day. On some days, we make many more than that, and sometimes those changes can be minor (like a typo correction), and other times they will be a huge reorganization or rewrite.

But there-in lies the other problem with any kind of monitoring of changes – our documentation is big and complex. Any ‘page watcher’ to notify you of changes would be limited by the fact that we split the reference manual into just over 2000 different HTML pages. And of course we do that for each manual (4.1, 5.0, 5.1, 5.1-maria, 5.4, and 6.0). For those keeping score, that’s about 12,000 different HTML pages for the reference manual alone.

If you want to talk printed pages (and why not), the Letter-sized PDF manuals for the main documents in English (reference manuals, GUI docs, the MySQL version reference (15 docs) constitutes about 17,300 pages of content.

We actually create 91 different documents from our English language repository, and 234 documents across all languages in up to 14 different output types (PDF, HTML, texinfo, txt, etc).

So to return to the original question, would a page monitoring service be possible?

Probably.

Would it be useful?

I’m in two minds about this. I can see the value of having a way to see changes, but if what you want is to be able to monitor changes in behavior, then most of the time this is documented in the changelog, and we have a number of different outputs available for viewing the changelog information in more useful ways.

Other, more minor changes, and in some case major rewrites wouldn’t feature in the changelog (because they don’t relate to a change in the product we are documenting). Whether you would find such changes useful is up to you. A rewrite normally means we’ve decided to change the content to make it clearer, or we’ve re-organized the information to make it flow better. Again, it doesn’t necessarily constitute a change to the product that wouldn’t otherwise be in the changelog.

Would it be practical?

Probably not – the sheer size of our documentation would mean that just providing the data on the changes would probably double the number of pages and information, and it wouldn’t always be clear whether the change were just a typo correction or a major rewrite. And tracking the changes if we change a page ID (which we do, from time to time), would it difficult to correctly identify changes across different pages that really had the same content.

Of course, I’m open to suggestion here, and we are doing things to further improve and enhance the content, and maybe this is something we will consider. But I’m open to input on whether this is needed.

Speaking at CommunityOne West

Sorry for the (relatively) short notice, but I will be talking at Sun’s CommunityOne conference in San Francisco on June 1st.

I’ll be talking about, and demonstrating, the DTrace probes we have put into MySQL in a joint presentation with Robert Lor who will be doing the same for Postgres.

CommunityOne West Badge

Our presentation is on the Monday afternoon.

Check out the CommunityOne West Conference Site for more details and registration.