MySQL Database Package
The database package is based on a modified version of Warren Gay's APQ MySQL binding. For full details on these routines, consult the APQ documentation.
There is an enumerated type in the db package that controls the verbosity of tracing:
type db.trace_mode_type is ( db.trace_none, db.trace_db, db.trace_apq, db.trace_full );
type db.trace_mode_type is ( db.trace_none, db.trace_db, db.trace_apq, db.trace_full );
There is an enumerated type that controls file access:
type mysql.mode_type is ( mysql.read, mysql.write, mysql.read_write );
There is an enumerated type in the db package that controls fetch order:
type db.fetch_mode_type is ( db.sequential_fetch, db.random_fetch );
There is an enumerated type in the db package that identifies the database engine:
type db.database_type is ( db.engine_postgresql, db.engine_mysql, db.engine_oracle, db.engine_sybase, db.engine_db2 );
mysql.append( s [, a] )
Append text s to the SQL query. The text is on the same line.
Example
mysql.append( s, " where customer_no > 5" );
Parameters
Param
Mode
Type
Default
Description
s
in
string
required
SQL query text
a
in
string
empty string
additional text to place after the text
Exceptions
An exception is thrown when out of memory.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Append
mysql.append_line( s )
Append text s to the SQL query and start a new line.
Example
mysql.append_line( s, "where customer_no > 5" );
Parameters
Param
Mode
Type
Default
Description
s
in
string
required
SQL query text
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Append_Line
mysql.append_quoted( s )
Append text s to SQL query while surrounding s with single quotes.
Example
mysql.append_quoted( "customer_name" );
Parameters
Param
Mode
Type
Default
Description
s
in
string
required
SQL query text
a
in
string
empty string
additional text to place after the text
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Append_Quoted
mysql.begin_work
Start a database transaction, marking the position of a possible rollback. The query will be erased.
Example
mysql.begin_work;
Parameters
none
Exceptions
in_abort_state exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.commit_work mysql.rollback_work
Compare With
Ada: APQ.Begin_Work
mysql.clear
Erase the text of the current query.
Example
mysql.clear;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Clear
mysql.close_db_trace
Stop tracing the database activity and close the trace file.
Example
mysql.close_db_trace;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.is_trace mysql.open_db_trace mysql.set_trace
Compare With
Ada: APQ.Clear
i := mysql.column_index( s )
Return the position of a query result column. This is the position in the query, not the database table.
Example
third_column_position := mysql.column_index( "first name" );
Parameters
Param
Mode
Type
Default
Description
s
in
string
required
the column heading
i
return value
column_index_type
required
the column position in the query
Exceptions
no_column exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.column_name
Compare With
Ada: APQ.Column_Index
s := mysql.column_name( c )
Return the name of a query result column. The number is the position in the query, not the database table.
Example
third_column_heading := mysql.column_name( 3 );
Parameters
Param
Mode
Type
Default
Description
c
in
column_index_type
required
the column position in the query results
s
return value
string
required
the column heading
Exceptions
no_column exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Column_Name PHP: mysql_field_name
n := mysql.columns
Return the number of columns (fields) from the last query.
Example
number_of_columns := mysql.columns;
Parameters
Param
Mode
Type
Default
Description
n
return value
natural
required
the number of columns
Exceptions
no_result exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Columns
mysql.commit_work
Complete a database transaction. The query will be erased.
Example
mysql.commit_work;
Parameters
none
Exceptions
in_abort_state exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.begin_work mysql.rollback_work
Compare With
Ada: APQ.Commit_Work
mysql.connect( d [, u, w ][, h][, p] )
Connect to database d using username u, password w, hostname h and port p. If no hostname or port are specified, connection is made by a UNIX socket instead of a network socket.
Example
mysql.connect( "db", "user", "password" );
Parameters
Param
Mode
Type
Default
Description
d
in
string
required
the database name
u
in
string
your username
the username to connect with
w
in
string
default password
username's password
h
in
string
UNIX Socket
hostname for network socket
p
in
string
default port
network socket port
Exceptions
If a connection cannot be made, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: combines several APQ functions
mysql.databases
Show a list of the databases available with the current connection. This
is the equivalent of MySQL "show databases".
Example
mysql.databases;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.list mysql.schema mysql.users
Compare With
-
mysql.disconnect
Close a connection created by connect.
Example
mysql.disconnect;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.connect
Compare With
Ada: APQ.Disconnect PHP: mysql_close
b := mysql.end_of_query
True if there are no more result (tuple) rows.
Example
while not mysql.end_of_query loop ...
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
true if no more rows
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.End_Of_Query
e := mysql.engine_of
Return the identity of the database engine
Example
e := mysql.engine_of;
Parameters
Param
Mode
Type
Default
Description
e
return value
db.database_type
db.engine_mysql, etc.
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Engine_Of
s := mysql.error_message
Last error message returned by database server.
Example
err := mysql.error_message;
Parameters
Param
Mode
Type
Default
Description
b
return value
string
required
last server message
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Error_Message; PHP: mysql_error
mysql.execute
Run a prepared database query.
Example
mysql.execute;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.show mysql.execute_checked
Compare With
Ada: APQ.Execute PHP: pg_execute
mysql.execute_checked( [ s ] )
Execute the query. If an error occurs, display the message s on
standard error and raise an exception. If an error occurs and there is
no error message s, display the query on standard error and raise an
exception.
Example
mysql.execute_checked( "message" );
Parameters
Param
Mode
Type
Default
Description
s
in
string
empty string
a message
Exceptions
An exception is thrown if an error occurs.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.show mysql.execute
Compare With
Ada: APQ.Execute_Checked
mysql.fetch [ (i) ]
Fetch the next query result tuple row, or a specific result row.
Example
mysql.fetch;
Parameters
Param
Mode
Type
Default
Description
i
in
tuple_index_type
next row
a specific result row
Exceptions
no_result or no_tuple exceptions may be raised.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Fetch PHP: mysql_fetch_array
s := mysql.in_abort_state
True if in abort state. If there is no connection, return false.
Example
b := mysql.in_abort_state;
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
true if in abort state
Exceptions
If a connection doesn't exist, a not connected exception will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.In_Abort_State
b := mysql.is_connected
True if a connection is open to a database.
Example
b := mysql.is_connected;
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
true if connected
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Is_Connected
b := mysql.is_null( c )
True if column in the fetch result is undefined.
Example
b := mysql.is_null;
Parameters
Param
Mode
Type
Default
Description
c
in
mysql.column_index_type
required
the field to check
b
return value
boolean
required
true if null
Exceptions
no_column and no_result exceptions may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Is_Null
b := mysql.is_trace
True if set_trace was true (that is, if debug tracing is enabled).
Example
b := mysql.is_trace;
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
tracing is enabled
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.close_db_trace mysql.open_db_trace mysql.set_trace
Compare With
Ada: APQ.Is_Trace
mysql.list
Show a list of the tables available in the current database. This is the
equivalent of MySQL's "show tables".
Example
mysql.list;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.databases mysql.schema mysql.users
Compare With
-
mysql.open_db_trace( f [,m] )
Begin tracing the database activity, storing the results at pathname f. m is an optional trace mode type
Example
mysql.open_db_trace( "./trace.out" );
Parameters
Param
Mode
Type
Default
Description
f
in
string
required
trace file pathname
m
in
mysql.trace_mode_type
mysql.trace_apq
trace type
Exceptions
If a connection doesn't exist, an error will occur.
not_connected, file already open, file not found exceptions may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.close_db_trace mysql.is_trace mysql.set_trace
Compare With
Ada: APQ.Open_DB_Trace
s := mysql.options
Return database options.
Example
s := mysql.options;
Parameters
Param
Mode
Type
Default
Description
s
return value
string
required
database options
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Options
mysql.prepare( s [, a] )
Prepare a SQL statement to execute. If a is included, insert the next statement after the statement named a.
Example
mysql.prepare( "select * from customers" );
Parameters
Param
Mode
Type
Default
Description
s
in
string
required
SQL statement
a
in
string
after all others
insert SQL statement after statement a
Exceptions
If a connection cannot be made, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Prepare
mysql.raise_exceptions( [ b ] )
True to raise exceptions on query errors.
Example
mysql.raise_exceptions( false );
Parameters
Param
Mode
Type
Default
Description
b
in
boolean
true
whether or not exceptions will occur
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Raise_Exceptions
mysql.report_errors( b )
True to report errors on query.
Example
mysql.report_errors( false );
Parameters
Param
Mode
Type
Default
Description
b
in
boolean
true
whether or not errors will be reported
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Report_Errors
mysql.reset
Reset the database connection: close open files, rollback query (if
necessary) and disconnect. Use disconnect instead unless you know what
you are doing.
Example
mysql.reset;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Reset
mysql.rewind
Return to the start of a query's results.
Example
mysql.rewind;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Rewind
mysql.rollback_work
Rollback a database transaction, undoing all work since begin_work. The query will be erased.
Example
mysql.rollback_work;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.begin_work mysql.commit_work
Compare With
Ada: APQ.Rollback_Work
mysql.schema( t )
Show information about the columns available in a table. This is the equivalent of MySQL's "show create table" or "desc".
Example
mysql.schema( "table" );
Parameters
Param
Mode
Type
Default
Description
t
in
string
required
name of the table
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.databases mysql.list mysql.users
Compare With
-
mysql.set_rollback_on_finalize( b )
Determine if a rollback will be issued when the script ends and the database connection is still open (true) or no rollback (false). Default is true.
Example
mysql.set_rollback_on_finalize( false );
Parameters
Param
Mode
Type
Default
Description
b
in
boolean
true
whether or not rollback will occur
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Set_Rollback_On_Finalize
mysql.set_trace( b )
Enable or disable query tracing. The trace file will remain open.
Example
mysql.set_trace( false );
Parameters
Param
Mode
Type
Default
Description
b
in
boolean
true
whether or not tracing will occur
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.close_db_trace mysql.is_trace mysql.open_db_trace
Compare With
Ada: APQ.Set_Trace
mysql.show
Run the prepared query and show the results in a table on standard output.
This is often used to show the results of a SQL SELECT statement.
Example
mysql.show;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.execute mysql.execute_checked
Compare With
-
t := mysql.tuple
Return the result row (tuple) number from the last fetch.
Example
row_number := mysql.tuple;
Parameters
Param
Mode
Type
Default
Description
t
return value
mysql.tuple_index_type
required
the current row number
Exceptions
no_tuple exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Tuple
n := mysql.tuples
Return the number of rows (tuples) from the last query.
Example
row_number := mysql.tuples;
Parameters
Param
Mode
Type
Default
Description
t
return value
mysql.tuple_count_type
required
the number of rows
Exceptions
no_result exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Tuples
mysql.users
Show a list of database users. This is similar to MySQL's "show grants". The
columns in the list depend on the database engine.
Example
mysql.users;
Parameters
none
Exceptions
If a connection doesn't exist, an error will occur.
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
mysql.execute mysql.execute_checked
Compare With
-
s := mysql.value( c )
Return the column value as a string.
Example
first_name := mysql.value( 3 );
Parameters
Param
Mode
Type
Default
Description
c
in
mysql.column_index_type
required
the field position to return
s
return value
universal_typeless
required
the value of the field
Exceptions
no_column, no_result, null_value and no_tuple exceptions may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Value
b := mysql.will_rollback_on_finalize
True if set_rollback_on_finalize was true (that is, that when the script finishes, a rollback will be issued if the connection is still open).
Example
b := mysql.will_rollback_on_finalize;
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
rollback will be issued on finalize
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_mysql_database restriction
See Also
-
Compare With
Ada: APQ.Will_Rollback_On_Finalize