DB (PostgreSQL) Package
The database package is based on a modified version of Warren Gay's APQ Postgres
binding. For full details on these routines, consult the APQ documentation.
There is an enumerated type that controls the verbosity of tracing:
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 db.mode_type is ( db.read, db.write, db.read_write );
There is an enumerated type that controls fetch order:
type db.fetch_mode_type is ( db.sequential_fetch, db.random_fetch );
There is an enumerated type 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 );
db.append( s [, a] )
Append text s to the SQL query. The text is on the same line.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Append
db.append_line( s )
Append text s to the SQL query and start a new line.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Append_Line PHP: pg_put_line
db.append_quoted( s, [a] )
Append text s to SQL query while surrounding s with single quotes.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Append_Quoted
db.begin_work
Start a database transaction, marking the position of a possible rollback. The query will be erased.
Example
db.begin_work;
Parameters
none
Exceptions
in_abort_state exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_postgresql_database restriction
See Also
db.commit_work db.rollback_work
Compare With
Ada: APQ.Begin_Work
db.clear
Erase the text of the current query.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Clear
db.close_db_trace
Stop tracing the database activity and close the trace file.
Example
db.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_postgresql_database restriction
See Also
db.is_trace db.open_db_trace db.set_trace
Compare With
Ada: APQ.Close_DB_Trace
PHP: pg_untrace
i := db.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 := db.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_postgresql_database restriction
See Also
db.column_name
Compare With
Ada: APQ.Column_Index PHP: pg_field_num
s := db.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 := db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Column_Name PHP: pg_field_name
n := db.columns
Return the number of columns (fields) from the last query.
Example
number_of_columns := db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Columns PHP: pg_num_fields
db.commit_work
Complete a database transaction. The query will be erased.
Example
db.commit_work;
Parameters
none
Exceptions
in_abort_state exception may be raised
Restrictions
Not allowed in a restricted shell Not allowed with no_postgresql_database restriction
See Also
db.begin_work db.rollback_work
Compare With
Ada: APQ.Commit_Work
db.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
db.connect( "ken" );
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_postgresql_database restriction
See Also
db.disconnect
Compare With
Ada: combines several APQ functions PHP: pg_connect / pg_pconnect
db.databases
Show a list of the databases available with the current connection. This
is the equivalent of PostgreSQL "\l".
Example
db.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_postgresql_database restriction
See Also
db.list db.schema db.users
Compare With
-
db.disconnect
Close a connection created by connect.
Example
db.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_postgresql_database restriction
See Also
db.connect
Compare With
Ada: APQ.Disconnect PHP: pg_close
b := db.end_of_query
True if there are no more result (tuple) rows.
Example
while not db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.End_Of_Query
b := db.engine_of
Return the identity of the database engine
Example
b := db.engine_of;
Parameters
Param
Mode
Type
Default
Description
b
return value
db.database_type
required
db.engine_postgresql, etc.
Exceptions
-
Restrictions
Not allowed in a restricted shell Not allowed with no_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Engine_Of
s := db.error_message
Last error message returned by database server.
Example
err := db.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_postgresql_database restriction
See Also
db.notice_message
Compare With
Ada: APQ.Error_Message PHP: pg_last_error / pg_last_notice
db.execute
Run a prepared database query.
Example
db.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_postgresql_database restriction
See Also
db.show db.execute_checked
Compare With
Ada: APQ.Execute PHP: pg_execute
db.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
db.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_postgresql_database restriction
See Also
db.show db.execute
Compare With
Ada: APQ.Execute_Checked
db.fetch [ (i) ]
Fetch the next query result tuple row, or a specific result row.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Fetch PHP: pg_fetch_array
s := db.in_abort_state
True if in abort state. If there is no connection, return false.
Example
b := db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.In_Abort_State
b := db.is_connected
True if a connection is open to a database.
Example
b := db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Is_Connected PHP: pg_connection_status
b := db.is_null( c )
True if column in the fetch result is undefined.
Example
b := db.is_null;
Parameters
Param
Mode
Type
Default
Description
c
in
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Is_Null PHP: pg_field_is_null
b := db.is_trace
True if set_trace was true (that is, if debug tracing is enabled).
Example
b := db.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_postgresql_database restriction
See Also
db.close_db_trace db.open_db_trace db.set_trace
Compare With
Ada: APQ.Is_Trace
db.list
Show a list of the tables available in the current database. This is the
equivalent of PostgreSQL's "\dt".
Example
db.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_postgresql_database restriction
See Also
db.databases db.schema db.users
Compare With
-
s := db.notice_message
Last notice message returned by database server.
Example
err := db.notice_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_postgresql_database restriction
See Also
db.error_message
Compare With
Ada: APQ.Notice_Message PHP: pg_last_notice
db.open_db_trace( f [,m] )
Begin tracing the database activity, storing the results at pathname f. m is an optional trace mode type
Example
db.open_db_trace( "./trace.out" );
Parameters
Param
Mode
Type
Default
Description
f
in
string
required
trace file pathname
m
in
db.trace_mode_type
db.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_postgresql_database restriction
See Also
db.close_db_trace db.is_trace db.set_trace
Compare With
Ada: APQ.Open_DB_Trace PHP: pg_trace
s := db.options
Return database options.
Example
s := db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Options PHP: pg_options
db.prepare( s [, a] )
Prepare a SQL statement to execute. If a is included, insert the next statement after the statement named a.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Prepare PHP: pg_prepare
db.raise_exceptions( [ b ] )
True to raise exceptions on query errors.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Raise_Exceptions
db.report_errors( b )
True to report errors on query.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Report_Errors
db.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
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Reset PHP: pg_connection_reset
db.rewind
Return to the start of a query's results.
Example
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Rewind PHP: pg_result_seek
db.rollback_work
Rollback a database transaction, undoing all work since begin_work. The query will be erased.
Example
db.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_postgresql_database restriction
See Also
db.begin_work db.commit_work
Compare With
Ada: APQ.Rollback_Work
db.schema( t )
Show information about the columns available in a table. This is the equivalent of PostgreSQL's "\d table".
Example
db.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_postgresql_database restriction
See Also
db.databases db.list db.users
Compare With
-
db.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
db.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_postgresql_database restriction
See Also
db.will_rollback_on_finalize
Compare With
Ada: APQ.Set_Rollback_On_Finalize
db.set_trace( b )
Enable or disable query tracing. The trace file will remain open.
Example
db.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_postgresql_database restriction
See Also
db.close_db_trace db.is_trace db.open_db_trace
Compare With
Ada: APQ.Set_Trace PHP: pg_trace / pg_untrace
db.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
db.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_postgresql_database restriction
See Also
db.execute db.execute_checked
Compare With
-
t := db.tuple
Return the result row (tuple) number from the last fetch.
Example
row_number := db.tuple;
Parameters
Param
Mode
Type
Default
Description
t
return value
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Tuple
n := db.tuples
Return the number of rows (tuples) from the last query.
Example
row_number := db.tuples;
Parameters
Param
Mode
Type
Default
Description
t
return value
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Tuples PHP: pg_num_rows
db.users
Show a list of database users. This is similar to PostgreSQL's "\du". The
columns in the list depend on the database engine.
Example
db.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_postgresql_database restriction
See Also
db.execute db.execute_checked
Compare With
-
s := db.value( c )
Return the column value as a string.
Example
first_name := db.value( 3 );
Parameters
Param
Mode
Type
Default
Description
c
in
db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Value
b := db.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 := db.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_postgresql_database restriction
See Also
-
Compare With
Ada: APQ.Will_Rollback_On_Finalize