LIBMYSQLD, embedded MySQL server library

25.1.1. An overview of the embedded MySQL server library

Using the embedded MySQL server library, you can use a MySQL server with full features in a client application. The main advantage is that it increases speed and makes the management of embedded applications easier.

The embedded server library is based on the MySQL client/server version and is written in C + + language. The result is that the embedded server is also written in C + + language. In other languages, the embedded server is not available.

The API is equivalent to the embedded MySQL version and the client/server version. To change the old thread application to use an embedded library, you normally simply add a call to the following function.

Function	When to call
Mysql_server_init ()	It should be called before any other MySQL function is called, preferably in the main () function.
Mysql_server_end ()	Should be called before the program exits.
Mysql_thread_init ()	Should be called in each thread that you create to access MySQL.
Mysql_thread_end ()	Should be called before Pthread_exit () is called.

You must then link your code with libmysqld.a, not libmysqlclient.a.

also included in Libmysqlclient.a is the mysql_server_xxx() function, which allows you to switch between the embedded version and the client/server version by linking the application to the appropriate library. See section 25.2, 12.1, "Mysql_server_init ()".

One difference between an embedded server and a standalone server is that, for an embedded server, connection authentication is forbidden by default. For an embedded server, to use the authentication feature, use "--with-embedded-privilege-control" When activating "Configure" To configure the MySQL distribution version Options.

25.1.2. Compiling a program with LIBMYSQLD

To get the libmysqld Library, you should configure MySQLwith the "--with-embedded-server" option. See section 2.8, 2, "Typical configuration options ".

When linking your program to Libmysqld, you must also include the system's Pthread library and some libraries used by the MySQL server. perform "mysql_config--libmysqld-libs" To get a complete list of libraries.

For the compilation and linking of threads, you must use the correct flags, even if you do not call any of the thread functions directly in your code.

To compile a C program to contain the necessary files and embed the MySQL server library into the compiled version of the program, you can use the GNU C compiler (gcc). The compiler needs to know the location of the various files and need to know how to compile the instructions for the program. In the following example, the method of how to compile a program from the command line is described:

GCC Mysql_test.c-o mysql_test-lz \

'/usr/local/mysql/bin/mysql_config--include--libmysqld-libs '

The name of the C program file is not compiled immediately after the GCC command. Next, the given "-o" option indicates that the file name behind it is the compiler will output the filename, which is the compiled program. In the next line of code, tell the compiler to get the location that contains the files and libraries, and other settings for the system on which it was compiled. The "-lz" option (compression) has been added here because of a problem with "mysql_config". The "mysql_config" section is included in the backticks , not in single quotes.

25.1.3. Limitations when using an embedded MySQL server

The following limitations exist for embedded servers:

· ISAM tables are not supported . (The main purpose of this is to make the library smaller).

· There are no custom functions (UDFs).

· There is no stack trace for the core dump.

· No internal raid support. (because most of the current operating system supports large files, it is not normally required).

· It cannot be set to "primary" or "from" (No replication).

· A large result set may not be available on a system with low memory.

· You cannot connect to an embedded server from an external process using sockets or TCP/IP. However, you can connect to an intermediate application, which can then connect to the embedded server on behalf of a remote client or an external process.

You can change some restrictions by editing the "mysql_embed.h" include file and recompiling MySQL.

25.1.4. Options for use with embedded servers

It can also be used with an embedded server library for any option that can be given with the mysqld Server Port Supervision program. In the array, you can assign the server option as a parameter to the mysql_server_init ()that is used to initialize the server. They can also be given in options files such as my.cnf . to specify an option file for a C program, use the "--defaults-file" option as the function Mysql_server_init () one of the elements of the first 2 parameters. For more information about the mysql_server_init () function, see section 25.2, 12.1, "Mysql_server_init ()".

Using the options file simplifies switching between client/server applications and embedded MySQL applications. Place common options in the [Server] group. They can be read by two versions of MySQL . The client/server option should be placed in the [mysqld] section. Place the options for the embedded MySQL Server Library in the [embedded] section. Place the application-related options in the section labeled [Applicationname_server] . see section 4.3.2, "Using option Files".

25.1.5. What remains to be done in the embedded server (TODO)

· We'll provide some options to save some parts of MySQL , making the library smaller.

· There is still a lot of speed optimization work to be done.

· The error will be written to stderr. We will add 1 options to specify a file name for them.

· with an embedded version, you need to change the InnoDBso that it is no longer verbose. If your database does not contain a InnoDB table, to suppress related messages, add "--skip-innodb" to the options file under Group [Libmysqd_server] option, or Add this option when initializing the server with mysql_server_init () .

25.1.6. Embedded Server Example

On Linux or FreeBSD systems, you can use the following two sample programs without changes. For other operating systems, minor modifications are required, primarily the file path. The purpose of designing these two examples is to provide you with enough detail information to understand the problem, which is a necessary part of the actual application. The first 1 examples are very intuitive. The 2 example uses some error checking functionality, which is slightly more complex. After the first 1 examples, a command line entry is given to compile the program. After the first 2 examples, the gnumake file is given, which can be used for compilation.

Example:1

Test1_libmysqld.c

#include <stdio.h>

#include <stdlib.h>

#include <stdarg.h>

#include "mysql.h"

MYSQL *mysql;

Mysql_res *results;

Mysql_row record;

static char *server_options[] = {"Mysql_test", "--defaults-file=my.cnf"};

int num_elements = sizeof (server_options)/sizeof (char *);

static char *server_groups[] = {"Libmysqld_server", "libmysqld_client"};

int main (void)

{

Mysql_server_init (num_elements, server_options, server_groups);

MySQL = Mysql_init (NULL);

Mysql_options (MySQL, Mysql_read_default_group, "libmysqld_client");

Mysql_options (MySQL, mysql_opt_use_embedded_connection, NULL);

Mysql_real_connect (MySQL, null,null,null, "Database1", 0,null,0);

mysql_query (MySQL, "select Column1, Column2 from table1");

Results = Mysql_store_result (mysql);

while (record = mysql_fetch_row (results))) {

printf ("%s-%s \ n", Record[0], record[1]);

}

Mysql_free_result (results);

Mysql_close (MySQL);

Mysql_server_end ();

return 0;

}

The following command-line commands are given to compile the above program:

GCC Test1_libmysqld.c-o test1_libmysqld-lz \

'/usr/local/mysql/bin/mysql_config--include--libmysqld-libs '

Example:2

To verify the example, create a test2_libmysqld directory that is peer to the MySQL source directory. Save test2_libmysqld.c source files and gnumakefile to this directory and run in test2_libmysqld directory GNUmake.

Test2_libmysqld.c

/*

* A Simple example client, using the embedded MySQL server library

*/

#include <mysql.h>

#include <stdarg.h>

#include <stdio.h>

#include <stdlib.h>

MYSQL *db_connect (const char *dbname);

void Db_disconnect (MYSQL *db);

void Db_do_query (MYSQL *db, const char *query);

const char *server_groups[] = {

"Test2_libmysqld_server", "embedded", "SERVER", NULL

};

Int

Main (int argc, char **argv)

{

MYSQL *one, *two;

/* Mysql_server_init () must is called before any other MySQL

* Functions.

*

* Can use Mysql_server_init (0, NULL, NULL), and it

* Initializes the server using groups = {

* "Server", "embedded", NULL

*  }.

*

* In your $HOME/.my.cnf file, you probably want to put:

[Test2_libmysqld_server]

Language =/path/to/source/of/mysql/sql/share/english

* You could, of course, modify argc and argv before passing

* them to this function. Or you could create new ones in any

* the like. But all of the arguments in argv (except for

* Argv[0], which is the program name) should be valid options

* for the MySQL server.

*

* If You link this client against the normal mysqlclient

* Library, this function is just a stubs that does nothing.

*/

Mysql_server_init (argc, argv, (char * *) server_groups);

one = Db_connect ("test");

both = Db_connect (NULL);

Db_do_query (One, "SHOW TABLE STATUS");

Db_do_query (both, "SHOW DATABASES");

Mysql_close (both);

Mysql_close (one);

/* This must is called after all other MySQL functions */

Mysql_server_end ();

Exit (exit_success);

}

static void

Die (MYSQL *db, char *fmt, ...)

{

Va_list ap;

Va_start (AP, FMT);

vfprintf (stderr, FMT, AP);

Va_end (AP);

(void) putc (' \ n ', stderr);

if (db)

Db_disconnect (DB);

Exit (Exit_failure);

}

MYSQL *

Db_connect (const char *dbname)

{

MYSQL *db = Mysql_init (NULL);

if (!DB)

Die (db, "Mysql_init failed:no Memory");

/*

* Notice the client and server use separate group names.

* This was critical, because the server does not accept the

* client ' s options, and vice versa.

*/

Mysql_options (DB, Mysql_read_default_group, "test2_libmysqld_client");

if (!mysql_real_connect (db, NULL, NULL, NULL, dbname, 0, NULL, 0))

Die (db, "Mysql_real_connect failed:%s", mysql_error (db));

return DB;

}

void

Db_disconnect (MYSQL *db)

{

Mysql_close (DB);

}

void

Db_do_query (MYSQL *db, const char *query)

{

if (mysql_query (db, query)! = 0)

Goto err;

if (Mysql_field_count (db) > 0)

{

Mysql_res *res;

Mysql_row ROW, End_row;

int num_fields;

if (! ( res = Mysql_store_result (db)))

Goto err;

Num_fields = Mysql_num_fields (res);

while (row = mysql_fetch_row (res)))

{

(void) fputs (">>", stdout);

for (End_row = row + num_fields; row < End_row; ++row)

(void) printf ("%s\t", row?) (char*) *row: "NULL");

(void) FPUTC (' \ n ', stdout);

}

(void) FPUTC (' \ n ', stdout);

Mysql_free_result (RES);

}

Else

(void) printf ("Affected Rows:%lld\n", mysql_affected_rows (db));

Return

Err:

Die (db, "Db_do_query failed:%s [%s]", mysql_error (db), query);

}

Gnumakefile

# This assumes the MySQL software is installed In/usr/local/mysql

inc: =/usr/local/mysql/include/mysql

Lib: =/usr/local/mysql/lib

# If you had not installed the MySQL software yet, try this instead

#inc: = $ (HOME)/mysql-5.1/include

#lib: = $ (HOME)/mysql-5.1/libmysqld

CC: = gcc

Cppflags: =-i$ (inc)-d_thread_safe-d_reentrant

CFLAGS: =-g-w-wall

Ldflags: =-static

# you can change-lmysqld to-lmysqlclient

# Client/server Library

Ldlibs =-l$ (lib)-lmysqld-lz-lm-lcrypt

IFNEQ (, $ (shell grep freebsd/copyright 2>/dev/null))

# FreeBSD

Ldflags + =-pthread

Else

# assume Linux

Ldlibs + =-lpthread

endif

# This works for simple one-file test programs

Sources: = $ (wildcard *.c)

Objects: = $ (Patsubst%c,%o,$ (sources))

Targets: = $ (basename $ (sources))

All: $ (targets)

Clean

Rm-f $ (Targets) $ (objects) *.core