MySQL Client Application Programming Interfaces

2.1 Introduction

This chapt er discusses how t o writ e program s t hat use MySQL. I t covers basic API operat ions t hat are fundam ent al t o your underst anding of t he recipes in lat er chapt ers, such as connect ing t o t he MySQL server, issuing queries, and ret rieving t he result s.

2.1.1 MySQL Client Application Programming Interfaces

This book shows how t o writ e MySQL-based program s using Perl, PHP, Pyt hon, and Java, and it s possible t o use several ot her languages as well. But one t hing all MySQL client s have in com m on, no m at t er which language you use, is t hat t hey connect t o t he server using som e kind of applicat ion program m ing int erface API t hat im plem ent s a com m unicat ions prot ocol. This is t rue regardless of t he program s purpose, whet her it s a com m and- line ut ilit y, a j ob t hat runs aut om at ically on a predet erm ined schedule, or a script t hat s used from a web server t o m ake dat abase cont ent available over t he Web. MySQL API s provide a st andard way for you, t he applicat ion developer, t o express dat abase operat ions. Each API t ranslat es your inst ruct ions int o som et hing t he MySQL server can underst and. The server it self speaks a low- level prot ocol t hat I call t he raw prot ocol. This is t he level at which direct com m unicat ion t akes place over t he net work bet ween t he server and it s client s. A client est ablishes a connect ion t o t he port on which t he server is list ening and com m unicat es wit h it by speaking t he client - server prot ocol in it s m ost basic t erm s. Basically, t he client fills in dat a st ruct ures and shoves t hem over t he net work. I t s not product ive t o at t em pt t o com m unicat e direct ly wit h t he server at t his level see t he sidebar Want t o Telnet t o t he MySQL Server? , nor t o writ e program s t hat do so. The raw prot ocol is a binary com m unicat ion st ream t hat is efficient , but not part icularly easy t o use, a fact t hat usually det ers developers from at t em pt ing t o writ e program s t hat t alk t o t he server t his way. More convenient access t o t he MySQL server is provided t hrough a program m ing int erface t hat is writ t en at a level above t hat of t he raw prot ocol level. The int erface handles t he det ails of t he raw prot ocol on behalf of your program s. I t provides calls for operat ions such as connect ing t o t he server, sending queries, ret rieving t he result s of queries, and obt aining query st at us inform at ion. Java drivers im plem ent t his low- level prot ocol direct ly. They plug int o t he Java Dat abase Connect ivit y JDBC int erface, so you writ e your program s using st andard JDBC calls. JDBC passes your request s for dat abase operat ions t o t he MySQL driver, which m aps t hem int o operat ions t hat com m unicat e wit h t he MySQL server using t he raw prot ocol. The MySQL drivers for Perl, PHP, and Pyt hon adopt a different approach. They do not im plem ent t he raw prot ocol direct ly. I nst ead, t hey rely on t he MySQL client library t hat is included wit h MySQL dist ribut ions. This client library is writ t en in C and t hus provides t he basis of an applicat ion program m ing int erface for com m unicat ing wit h t he server from wit hin C program s. Most of t he st andard client s in t he MySQL dist ribut ion are writ t en in C and use t his API . You can use it in your own program s, t oo, and should consider doing so if you want t he m ost efficient program s possible. However, m ost t hird- part y applicat ion developm ent is not done in C. I nst ead, t he C API is m ost oft en used indirect ly as an em bedded library wit hin ot her languages. This is how MySQL com m unicat ion is im plem ent ed for Perl, PHP, Pyt hon, and several ot her languages. The API for t hese higher- level languages is writ t en as a wrapper around t he C rout ines, which are linked int o t he language processor. The benefit of t his approach is t hat it allows a language processor t o t alk t o t he MySQL server on your behalf using t he C rout ines while providing t o you an int erface in which you express dat abase operat ions m ore convenient ly. For exam ple, script ing languages such as Perl t ypically m ake it easy t o m anipulat e t ext wit hout having t o allocat e st ring buffers or dispose of t hem when youre done wit h t hem t he way you do in C. Higher- level languages let you concent rat e m ore on what youre t rying t o do and less on t he det ails t hat you m ust t hink about when youre writ ing direct ly in C. This book doesnt cover t he C API in any det ail, because we never use it direct ly; t he program s developed in t his book use higher- level int erfaces t hat are built on t op of t he C API . However, if youd like t o t ry writ ing MySQL client program s in C, t he following sources of inform at ion m ay be helpful: • The MySQL Reference Manual cont ains a chapt er t hat provides a reference for t he C API funct ions. You should also have a look at t he source for t he st andard MySQL client s provided wit h t he MySQL source dist ribut ion t hat are writ t en in C. Source dist ribut ions and t he m anual bot h are available at t he MySQL web sit e, ht t p: www.m ysql.com , and you can obt ain t he m anual in print ed form from OReilly Associat es. • The book MySQL New Riders cont ains reference m at erial for t he C API , and also includes a chapt er t hat provides det ailed t ut orial inst ruct ions for writ ing MySQL program s in C. I n fact , you neednt even buy t he book t o get t his part icular chapt er; it s available in PDF form at ht t p: www.kit ebird.com m ysql-book . The source code for t he sam ple program s discussed in t he chapt er is available from t he sam e sit e for you t o st udy and use. These program s were deliberat ely writ t en for inst ruct ional purposes, so you m ay find t hem easier t o underst and t han t he st andard client s in t he MySQL source dist ribut ion. Want to Telnet to the MySQL Server? Som e net working prot ocols such as SMTP and POP are ASCI I based. This m akes it possible t o t alk direct ly t o a server for t hose prot ocols by using Telnet t o connect t o t he port on which t he server is list ening and t yping in com m ands from t he keyboard. Because of t his, people som et im es assum e t hat it should also be possible t o com m unicat e wit h t he MySQL server t he sam e way: by opening a Telnet connect ion t o it and ent ering com m ands. That doesnt work, due t o t he binary nat ure of t he raw prot ocol t hat t he server uses. You can verify t his for yourself. Suppose t he MySQL server is running on t he local host and list ening on t he default port 3306 . Connect t o it using t he following com m and: telnet localhost 3306 Youll see som et hing t hat looks like a version num ber, probably accom panied by a bunch of gibberish charact ers. What youre seeing is t he raw prot ocol. You cant get very far by com m unicat ing wit h t he server in t his fashion, which is why t he answer t o t he com m on quest ion, How can I Telnet t o t he MySQL server? is, Dont bot her. The only t hing you can find out t his way is whet her or not t he server is up and list ening for connect ions on t he port . MySQL client API s provide t he following capabilit ies, each of which is covered in t his chapt er: • Con n e ct in g t o t h e M ySQL se r ve r ; se le ct in g a da t a ba se ; discon n e ct in g fr om t h e se r ve r . Every program t hat uses MySQL m ust first est ablish a connect ion t o t he server, and m ost program s also will specify which dat abase t o use. Som e API s expect t he dat abase nam e t o be supplied at connect t im e which is why connect ing and select ing are covered in t he sam e sect ion . Ot hers provide an explicit call for select ing t he dat abase. I n addit ion, well- behaved MySQL program s close t he connect ion t o t he server when t heyre done wit h it . • Ch e ck in g for e r r or s. Many people writ e MySQL program s t hat perform no error checking at all, which m akes t hem difficult t o debug when t hings go wrong. Any dat abase operat ion can fail and you should know how t o find out when t hat occurs and why. This is necessary so t hat you can t ake appropriat e act ion such as t erm inat ing t he program or inform ing t he user of t he problem . • I ssu in g qu e r ie s a n d r e t r ie vin g r e su lt s. The whole point of connect ing t o a dat abase server is t o run queries. Each API provides at least one way t o issue queries, as well as several funct ions for processing t he result s of queries. Because of t he m any opt ions available t o you, t his sect ion is easily t he m ost ext ensive of t he chapt er. • Usin g pr e pa r e d st a t e m e n t s a n d pla ce h olde r s in qu e r ie s. One w ay t o w rit e a query t hat refers t o specific dat a values is t o em bed t he values direct ly in t he query st ring. Most API s provide anot her m echanism t hat allows you t o prepare a query in advance t hat refers t o t he dat a values sym bolically. When you execut e t he st at em ent , you supply t he dat a values separat ely and t he API places t hem int o t he query st ring for you. • I n clu din g spe cia l ch a r a ct e r s a n d N ULL va lu e s in qu e r ie s. Som e charact ers such as quot es and backslashes have special m eaning in queries, and you m ust t ake cert ain precaut ions when const ruct ing queries cont aining t hem . The sam e is t rue for NULL values. I f you do not handle t hese properly, your program s m ay generat e SQL st at em ent s t hat are erroneous or t hat yield unexpect ed result s. This sect ion discusses how t o avoid t hese problem s. • H a n dlin g N ULL va lu e s in r e su lt se t s. NULL values are special not only when you const ruct queries, but in result s ret urned from queries. Each API provides a convent ion for dealing wit h t hem . To writ e your own program s, it s necessary t o know how t o perform each of t he fundam ent al dat abase API operat ions no m at t er which language you use, so each one is shown in each of our languages PHP, Perl, Pyt hon, and Java . Seeing how each API handles a given operat ion should help you see t he correspondences bet ween API s m ore easily and facilit at e underst anding of recipes shown in t he following chapt ers, even if t heyre writ t en in a language you dont use very m uch. Lat er chapt ers usually illust rat e recipe im plem ent at ions using j ust one or t wo languages. I recognize t hat it m ay seem overwhelm ing t o see each recipe in four different languages if youre int erest ed only in one part icular API . I n t hat case, I advise you t o approach t he recipes as follows: read j ust t he int roduct ory part t hat provides t he general background, t hen go direct ly t o t he sect ion for t he language in which youre int erest ed. Skip t he ot her languages. Should you develop an int erest in writ ing program s in ot her languages lat er, you can always com e back and read t he ot her sect ions t hen. This chapt er also discusses t he following t opics, which are not direct ly part of MySQL API s but can help you use t hem m ore easily: • W r it in g libr a r y file s. As you writ e program aft er program , you m ay find t hat t here are cert ain operat ions you carry out repeat edly. Library files provide a way t o encapsulat e t he code for t hese operat ions so t hat you can perform t hem from m ult iple script s wit hout including all t he code in each script . This reduces code duplicat ion and m akes your program s m ore port able. This sect ion shows how t o writ e a library file for each API t hat includes a funct ion for connect ing t o t he server—one operat ion t hat every program t hat uses MySQL m ust perform . Lat er chapt ers develop addit ional library rout ines for ot her operat ions. • W r it ing a n obj e ct - or ie n t e d M ySQL in t e r fa ce for PH P. The API s for Perl, Pyt hon, and Java each are class-based and provide an obj ect - orient ed program m ing m odel based on a dat abase- independent archit ect ure. PHPs built - in int erface is based on MySQL- specific funct ion calls. The sect ion describes how t o writ e a PHP class t hat can be used t o t ake an obj ect - orient ed approach t o developing MySQL script s. • W a ys of obt a in in g con n e ct ion pa r a m e t e r s. The earlier sect ion on est ablishing connect ions t o t he MySQL server relies on connect ion param et ers hardwired int o t he code. However, t here are several ot her ways t o obt ain param et ers, ranging from st oring t hem in a separat e file t o allowing t he user t o specify t hem at runt im e. To avoid t yping in t he exam ple program s, you should obt ain t he recipes source dist ribut ion see Appendix A . Then when an exam ple says som et hing like creat e a file nam ed xyz t hat cont ains t he following inform at ion . . . you can j ust use t he corresponding file from t he recipes dist ribut ion. The script s for t his chapt er are locat ed under t he api direct ory, wit h t he except ion of t he library files, which can be found in t he lib direct ory. The prim ary t able used for exam ples in t his chapt er is nam ed profile . I t s creat ed in Recipe 2.5 , which you should know in case you skip around in t he chapt er and wonder where it cam e from . See also t he not e at t he very end of t he chapt er about reset t ing t he profile t able t o a known st at e for use in ot her chapt ers.

2.1.2 Assumptions