Hi Jyri, thanks for very good comments. I have tried to make some answers (and more questions) in-line
Jyri Virkki wrote: > Jan S Berg wrote: >> A first draft for the MySQL ARC case is posted at: >> >> http://wikis.sun.com/display/WebStack/MySQL50ArcCase > > A handful of comments/questions: > >> This case seeks Major Release Binding. > > This nees to be Minor (at most). Yes, this should in-fact be micro, as changes (and upgrade procedures for database tables) for mysql is between minor and major versions. > >> 2.1. Key objects >> >> MySQL objects (Server): > > I realize several previous cases have listed these sections but I'm > finding it very repetitive. I see sections 2.1, 2.4 and Appendix 1 > repeating essentially the same layout info. Having the full listing in > the Appendix is nice, so I'd just suggest combining the content of 2.1 > & 2.4. That'll reduce the repetition and make the doc easier to maintain. ok, will change this. > >> /usr/mysql/5.0/share/mysql >> /usr/mysql/5.0/share/binary-configure > > Can you say a bit more about these? binary-configure is just another startup script, so will move this to appendix, and update the 2.1 and 2.4 sections as you suggested above. > >> 2.2 Versioning > > The stability of the upstream code between major/minor/micro versions > drives a number of decisions in the rest of the case. For that reason, > I'd like to see a summary here on how compatible MySQL remains within > minor & major release families. Do you expect all future 5.0.* to be > fully compatible? How about 5.1? Or 6.x? Does the MySQL community > make explicit promises on future compatibility? Historically, how > compatible have these been? There are two things about compatibility which should be mentioned, one for interfaces, and one for database data itself. First, MySQL is fairly stable at interfaces. It is committed to using standards like SQL and client interfaces like JDBC, ODBC, and second MySQL users is expecting to be able to migrate between different versions without changing their code/scripts. Most changes from version to version is new functionality and improvements in performance, security, etc. On the other hand there is no promise for compatibility. Secondly, compatibility between database data in different releases is being addressed by a mysql_upgrade script. It upgrades tables and data between major-minor versions (ie between 4.0 -> 4.1 and 4.1 to 5.0, etc) > > (There's 1 sentence about this in s.7.1, but more info will be helpful > here.) > >> 2.4 Directory Naming and Structure >> >> The proposed directory layout for MySQL is >> /usr/mysql/5.0 > > Provide at least a paragraph explaining the choice of versioned layout > here, given the compatibility info [to be added] in 2.2. > > Can I infer that 5.0.* will be compatible but 5.1 won't? Yes, at least we cannot be sure about 5.1 compatibility with 5.0 > >> /bin >> /doc >> /etc >> /lib >> /include >> /info >> /man/man1 >> /man/man8 >> /mysql-test >> /share >> /src >> /sql-bench >> /etc >> /var/mysql >> /datadir/ > > Many are obvious here, but I suggest providing a short (few words) > description of what goes in each location. What goes in share? src? > info? ok, will do that. > >> /usr/mysql/ will expose bin, include, lib, man, share, and src >> directorie s.These will be symbolic links to corresponding directories >> in the highest numb ered <version>.<subversion>.<minor-subversion> >> directory in /usr/mysql hence, u sers will be able to use >> "/usr/mysql/bin/mysqld" to invoke the most recent vers ion. > > Be aware that previous cases like PHP considered and rejected this > symlinking. Will the documentation recommend writing scripts which > invoke /usr/mysql/bin/mysql for example? What happens when an > incompatible version (be it 5.1 or 6) is installed? > > Other components like perl do provide this linking. So it's been done > both ways. My suggestion is to consider the use cases carefully and > include a paragraph in the case explaining the reasoning of your > choice, whichever approach you choose. Good point. An upgrade of MySQL will have issues both with interface and with data on upgrade. On the other hand, I see most Linux distribution has the binaries directly in /usr/bin or sbin, we should maybe consider doing the same? This means they will run into the same issues... (Or the users should be very aware of that they are doing an upgrade) > >> 2.5 Configuration and Enviroment settings. >> >> The mysql server (bin/mysqld) uses (and clients can use) configuration fil >> to start. > > The daemon and the client read the same config file? Yes, "all" MySQL programs can read the same configuration file. They will have different sections in the same file. > >> The search path for thiss configuration file is as follows: >> 1. /etc/my.cnf > > I guess that is fine, but obscurely named files in /etc are not great, > IMO. I see debian, for example, creates /etc/mysql/my.conf, which makes > obvious what it is. Have you considered this approach? I'm aware it's not exactly a good name for a config file, but this is the default when downloading from MySQL. Since Debian and Ubuntu uses /etc/mysql/my.conf it would be ok to put this in /etc/mysql for OpenSolaris as well, as long as we have it well documented. > >> 2. $MYSQL_HOME/my.cnf >> 3. specified on command line with --defaults-extra-file=<path> >> 4. in user home: ~/.my.cnf > > Do these apply to the server as well or just the client 'mysql'? For all Mysql programs that can read config files (so both mysqld server and mysql client at least). > > What does #3 mean to the server if it is started (as is the default) > via smf? With using smf, you want to use the default config file (/etc/mysql/my.cnf) only. > > Which user will mysqld run as? root? So it reads /.my.cnf? Not the > best place for mysqld configuration ;-) It can run as any user, but root is not a good choice :) > > Is the order in which you listed these significant? Does it stop as > soon as one is found or does the last one found override or does it > read all of them and try to merge config from each? It will merge, and the last one will override the previous. I will update the ARC case with some more specifics here. (Details can be found here: http://mysql.org/doc/refman/5.0/en/option-files.html) > >> For MySQL we will provide a sample configuration file which can be >> used by users in one of these search paths. The sample configuration >> file will be in /usr/mysql/5.0/etc/s ample_my.cnf > > One of the goals of web stack is easy out of the box experience. > > I'd like to see this project deliver a working configuration in > somewhere under /etc, tuned as necessary to work best on OpenSolaris. > > When creating the default config also keep in mind safe & sane > defaults, for example for "bind-address" you'd probably want > 127.0.0.1, etc. > > If you decide it is useful, you could also deliver the sample config > file from the upstream distribution as-is, possibly in the > /usr/mysql/5.0/etc/sample_my.cnf location shown above. But do deliver > a tuned, working copy under /etc. ok, this sounds fine, will update the document. There are also sample configuration files given by the MySQL distribution, I guess that could be sufficient for samples. Then we provide a default, working one in /etc/mysql. Does the default configuration file need to part of the ARC case (or can content be given at a later time) ? > > >> 3. Core Modules >> >> These are the proposed (statically linked) modules enabled by initial >> integration. >> >> MySQL server >> InnoDB - ACID storage engine >> MyIsam - non-ACID storage engine > > Are the just ./configure time options or external modules? Is the > "statically linked" comment just a detail? Would anything be different > if they were dynamically linked? I think I will rewrite this as the MySQL server has built in two (main) different storage engine, which you can choose for each table you create, where MyIsam is the default. > >> 4.1. Manual Pages. >> >> MySQL provides a man page, which will be delivered in the >> appropriate m an directory. >> [/usr/mysql/[<version>.<subversion>.<minor-subversion>]/man], with an > > Maybe a typo, but here the versioning is inconsistent with rest of doc? ok, will update this to be consistent. > > >> SUNWmysql50src - MySQL src > > The source lives in opensolaris, why a package for it? Or is this > something else entirely, like src for modules customers need to > recompile or such? No, as you say the source lives in OpenSolaris, so will remove this package. > >> 7.3. Exported Interfaces >> >> NAME STABILITY NOTES >> E01 MySQL Server Volatile Server deamon > > The daemon itself isn't an interface, just a process that runs. > Can you expand on the intent for this line? The intention is the server program, with all the options it has. > >> E02 MySQL C API Volatile - > > A Volatile API isn't very useful... (more below). Will change all the stability levels, since I think I miss-understood how to use them at first. > >> E06 Utilities Volatile Database management ut > > Does this cover everything in the bin directory? Yes, should we write an interface listing for each program/script? > >> E10 MySQL Server config file Volatile Sample config file > > The interface is the syntax of the config file, not the sample per se. Yes, that was the intention, will remove sample. > >> E11 MySQL Data/Log Directory Volatile - > > It's location? Or format? Is the data file format public at all? > Logs are probably Not An Interface? Will propose to change this to project private and change from "Directory" to "Files". Should maybe also state that database logs are not the same as logs in traditional sense, but files containing the transactional logs of the database (not human readable). > >> E20 TCP listen port Volatile - > > Which is it? Default the port is 3306, but can be changed in the configuration file. > >> E21 PID file Volatile database deamon pid fi > > Does this really need to be public? (since smf is the public interface > for start/stop). Yes, should be changed to Project Private. > >> E30 Man pages Volatile > > I wouldn't bother listing this, it is for human eyes only. ok, will remove it. > >> E31 Error messages Volatile I18N > > Messages (like logs) are probably Not An Interface (unless the MySQL > community specifically documents them). Error codes might be documented? Ok, it was the internationalized error codes I meant, so should that be listed here? > >> As this is OSS, we have no control over the stability of the >> interfaces, an d hence the classification as "Volatile" for most >> interfaces. > > Volatile is undesirable. Basically it means nobody can rely on MySQL > since the interfaces break every time there a few bug fixes. > > But more to the point, you're saying you might overwrite /usr/mysql > with incompatible versions at any time. If so, why provide versioning > in the form of /usr/mysql/5.0/? A benefit of the versioned layout is > that you can keep the content of /usr/mysql/5.0/ compatible; if an > incompatible 5.1 comes out you can place it in /usr/mysql/5.1 instead. Yes, I think it should be Committed or Project Private for the MySQL interfaces given here, I will update the document. Also it is a bit different how detailed the interface listing is at different projects, so I'm not sure which should be listed or not. > > > > >> /usr/mysql/5.0/lib/libdbug.a >> /usr/mysql/5.0/lib/libheap.a >> /usr/mysql/5.0/lib/libmyisam.a >> /usr/mysql/5.0/lib/libmyisammrg.a >> /usr/mysql/5.0/lib/libmysqlclient.a >> /usr/mysql/5.0/lib/libmysqlclient.la >> /usr/mysql/5.0/lib/libmysqlclient_r.a >> /usr/mysql/5.0/lib/libmysqlclient_r.la >> /usr/mysql/5.0/lib/libmystrings.a >> /usr/mysql/5.0/lib/libmysys.a >> /usr/mysql/5.0/lib/libvio.a >> /usr/mysql/5.0/lib/libz.a >> /usr/mysql/5.0/lib/libz.la > > How are these used, by whom? > > These are used for making c-api clients Thanks, Jan S
