[SparForte][Banner]
[Top Main Menu] Intro | Tutorials | Reference | Packages | Examples | Contributors   [Back Page]      [Next Page]  

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

 
[Right Submenu]

 Summary

 arrays

 btree_io

 calendar

 cgi

 chains

 command_line

 db/ postgresql

 dbm

 directory_operations

 doubly_linked...

 dynamic_hash_...

 enums

 exceptions

 files

 gnat.cgi

 gnat.crc32

 hash_io

 lock_files

 memcache

 memcache.highread

 mysql

 mysqlm

 numerics

 os

 pen

 pen (OpenGL)

 records

 sound

 source_info

 stats

 strings

 System

 teams

 templates

 text_io

 units

[Back to Top] Back To Top [Small Forte Symbol]