| Prev | Chapter�11.�Development Reference | Next |
|---|
+
By Pete Su and Jon Salz. Modified by Roberto Mello. -
+
One of OpenACS's great strengths is that code written for it is very close to the database. It is very easy to interact with the database from anywhere within OpenACS. Our goal is to develop a coherent API for database access which makes this even easier.
More detailed information about the DB api is available at Database Access API. -
Introduced in ACS 3.4, the new Database API is meant to save developers from the above tedium and provide a more structured syntax for specifying database operations, including transactions. Here's an example of the API.
set count 0
-set tcl_var "foo"
+set tcl_var "foo"
set sql {
select
@@ -45,13 +44,13 @@
No explicit code for grabbing and releasing handles. Usage of the
Database API implicitly deals with all handle management issues.
- The new command db_transaction + The new command db_transaction makes the scope of a transaction - clear. db_transaction takes the + clear. db_transaction takes the code block argument and automatically runs it in the context of a transaction.
- The new command db_foreach writes + The new command db_foreach writes our old while loop for us.
Every SQL query has a name, meant to be unique within the server @@ -61,7 +60,7 @@ from a Tcl variable to the database, which we'll cover next.
-
Bind variables are placeholders for literal values in an SQL query being sent to the server. Take the example query above: in the old way, data was generally passed to Oracle directly, via Tcl string @@ -117,18 +116,18 @@ where some_table.id = some_other_table.id and some_table.condition_p = ?
- The '?' character means "This will be filled in later with literal - data". In use, you might write code that looks like this: + The '?' character means "This will be filled in later with literal + data". In use, you might write code that looks like this:
-set statement [prepare_query "
+set statement [prepare_query "
select
foo,
bar,
baz
from some_table, some_other_table
where some_table.id = some_other_table.id
and some_table.condition_p = ?
- "]
+ "]
[bind_param $statement 1 $tcl_var]
@@ -170,8 +169,8 @@ query, and Tcl style string interpolation does not happen. So you cannot do something like:
-set table "baz"
-set condition "where foo = bar"
+set table "baz"
+set condition "where foo = bar"
db_foreach my_query { select :table from some_table where :condition }
@@ -183,24 +182,24 @@ Finally, the DB API has several different styles for passing bind variable values to queries. In general, use the style presented here because it is the most convenient. -
Every db_* command accepting a SQL command as an argument +
Every db_* command accepting a SQL command as an argument supports bind variables. You can either
- Specify the -bind switch to provide a set with bind variable + Specify the -bind switch to provide a set with bind variable values, or
- Specify the -bind switch to explicitly provide a list of + Specify the -bind switch to explicitly provide a list of bind variable names and values, or
Not specify a bind variable list at all, in which case Tcl variables are used as bind variables.
- The default behavior (i.e., if the -bind switch is omitted) is + The default behavior (i.e., if the -bind switch is omitted) is that these procedures expect to find local variables that correspond in name to the referenced bind variables, e.g.:
set user_id 123456
-set role "administrator"
+set role "administrator"
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -210,18 +209,18 @@
and map.role = :role
} {
# do something for each group of which user 123456 is in the role
- # of "administrator"
+ # of "administrator"
}
- The value of the local Tcl variable user_id (123456) is bound to - the user_id bind variable. -
The -bind switch can takes the name of an ns_set + The value of the local Tcl variable user_id (123456) is bound to + the user_id bind variable. +
The -bind switch can takes the name of an ns_set containing keys for each bind variable named in the query, e.g.:
set bind_vars [ns_set create]
ns_set put $bind_vars user_id 123456
-ns_set put $bind_vars role "administrator"
+ns_set put $bind_vars role "administrator"
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -231,11 +230,11 @@
and map.role = :role
} -bind $bind_vars {
# do something for each group in which user 123456 has the role
- # of "administrator"
+ # of "administrator"
}
- Alternatively, as an argument to -bind you can specify a list of + Alternatively, as an argument to -bind you can specify a list of alternating name/value pairs for bind variables:
@@ -245,22 +244,22 @@
where g.group_id = map.user_id
and map.user_id = :user_id
and map.role = :role
-} -bind [list user_id 123456 role "administrator"] {
+} -bind [list user_id 123456 role "administrator"] {
# do something for each group in which user 123456 has the role
- # of "administrator"
+ # of "administrator"
}
- When processing a DML statement, Oracle coerces empty strings into - null. (This coercion does not occur in the - WHERE clause of a query, i.e. - col = '' and - col is null are not equivalent.) + null. (This coercion does not occur in the + WHERE clause of a query, i.e. + col = '' and + col is null are not equivalent.)
As a result, when using bind variables, the only way to make Oracle set a - column value to null is to set the corresponding bind variable + column value to null is to set the corresponding bind variable to the empty string, since a bind variable whose value is the string - "null" will be interpreted as the literal string - "null".
These Oracle quirks complicate the process of writing clear and abstract + "null" will be interpreted as the literal string + "null".
These Oracle quirks complicate the process of writing clear and abstract DML difficult. Here is an example that illustrates why:
#
@@ -272,47 +271,47 @@
# );
#
-set bar ""
-set baz ""
+set bar ""
+set baz ""
-db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
+db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
#
-# the values of the "bar" and "baz" columns in the new row are both
+# the values of the "bar" and "baz" columns in the new row are both
# null, because Oracle has coerced the empty string (even for the
-# numeric column "bar") into null in both cases
+# numeric column "bar") into null in both cases
Since databases other than Oracle do not coerce empty strings into - null, this code has different semantics depending on the + null, this code has different semantics depending on the underlying database (i.e., the row that gets inserted may not have null as its column values), which defeats the purpose of SQL abstraction.
Therefore, the Database Access API provides a database-independent way to - represent null (instead of the Oracle-specific idiom of the - empty string): db_null.
Use it instead of the empty string whenever you want to set a column value - explicitly to null, e.g.:
+ represent null (instead of the Oracle-specific idiom of the + empty string): db_null.Use it instead of the empty string whenever you want to set a column value + explicitly to null, e.g.:
set bar [db_null] set baz [db_null] -db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)" +db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)" # -# sets the values for both the "bar" and "baz" columns to null +# sets the values for both the "bar" and "baz" columns to null -
The database library can transparently maintain pools of sequence values, so - that each request for a new sequence value (using db_nextval) + that each request for a new sequence value (using db_nextval) does not incur a roundtrip to the server. For instance, this functionality is very useful in the security/sessions library, which very frequently allocates - values from the sec_id_seq sequence. To utilize this + values from the sec_id_seq sequence. To utilize this functionality for a particular sequence, register the sequence to be pooled, - either using the db_register_pooled_sequence procedure at server + either using the db_register_pooled_sequence procedure at server startup time, or by including a configuration parameter of the form
PoolSequence.sequence_name_seq=count
- in any configuration section in the yourservername.ini + in any configuration section in the yourservername.ini file, e.g., e.g.,
@@ -324,49 +323,49 @@
startup. It will periodically scan pools and allocate new values for
sequences which are less than half-full. (This normally occurs every 60
seconds, and is configurable via the
- PooledSequenceUpdateInterval parameter in the
- [ns/server/
- yourservername
- /acs/database] configuration
+ PooledSequenceUpdateInterval parameter in the
+ [ns/server/
+ yourservername
+ /acs/database] configuration
section.)
- The Database API has several functions that wrap familiar parts of the AOLserver database API.
- Note that you never have to use ns_db anymore (including - ns_db gethandle)! Just start doing stuff, and (if you want) call - db_release_unused_handles when you're done as a hint to + Note that you never have to use ns_db anymore (including + ns_db gethandle)! Just start doing stuff, and (if you want) call + db_release_unused_handles when you're done as a hint to release the database handle.
db_abort_transaction
Aborts all levels of a transaction. That is if this is called within several nested transactions, all of them are terminated. Use this insetead of - db_dml "abort" "abort transaction". + db_dml "abort" "abort transaction". -
+
db_multirow [ -local ] [ -append ] [ -extend column_list ] \ var-name statement-name sql \ [ -bind bind_set_id | -bind bind_value_list ] \ code_block [ if_no_rows if_no_rows_block ]
- Performs the SQL query sql, saving results in variables + Performs the SQL query sql, saving results in variables of the form - var_name:1, var_name:2, etc, - setting var_name:rowcount to the total number - of rows, and setting var_name:columns to a + var_name:1, var_name:2, etc, + setting var_name:rowcount to the total number + of rows, and setting var_name:columns to a list of column names.
Each row also has a column, rownum, automatically added and set to the row number, starting with 1. Note that this will override any column in the SQL statement named 'rownum', also if you're using the Oracle rownum pseudo-column.
- If the -local is passed, the variables defined + If the -local is passed, the variables defined by db_multirow will be set locally (useful if you're compiling dynamic templates in a function or similar situations).
@@ -379,19 +378,19 @@ multirow.
You may also add additional, computed columns to the multirow, using the - -extend { col_1 col_2 ... } switch. This is + -extend { col_1 col_2 ... } switch. This is useful for things like constructing a URL for the object retrieved by the query.
If you're constructing your multirow through multiple queries with the same set of columns, but with different rows, you can use the - -append switch. This causes the rows returned by this query + -append switch. This causes the rows returned by this query to be appended to the rows already in the multirow, instead of starting a clean multirow, as is the normal behavior. The columns must match the columns in the original multirow, or an error will be thrown.
- Your code block may call continue in order to skip a row - and not include it in the multirow. Or you can call break + Your code block may call continue in order to skip a row + and not include it in the multirow. Or you can call break to skip this row and quit looping.
@@ -408,22 +407,22 @@ }
-db_null +db_null
Returns a value which can be used in a bind variable to represent the SQL value - null. + null. See Nulls and Bind Variables above.
Performs the SQL query - sql + sql , executing - code_block + code_block once for each row with variables set to column values (or a set or array populated if - -column_array or - column_set is + -column_array or + column_set is specified). If the query returns no rows, executes - if_no_rows_block + if_no_rows_block (if provided).
Example:
-db_foreach select_foo "select foo, bar from greeble" {
- doc_body_append "<li>foo=$foo; bar=$bar\n"
+db_foreach select_foo "select foo, bar from greeble" {
+ doc_body_append "<li>foo=$foo; bar=$bar\n"
} if_no_rows {
- doc_body_append "<li>There are no greebles in the database.\n"
+ doc_body_append "<li>There are no greebles in the database.\n"
}
- The code block may contain break statements (which terminate the - loop and flush the database handle) and continue statements + The code block may contain break statements (which terminate the + loop and flush the database handle) and continue statements (which continue to the next row of the loop).
Performs the SQL query - sql, + sql
, setting variables to column values. Raises an error if the query does not return exactly 1 row.Example:
-db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id" +db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id" # Bombs if there's no such greeble! # Now $foo and $bar are set.
Performs the SQL query - sql. + sql. If a row is returned, sets variables to column values and returns 1. If no rows are returned, returns 0. If more than one row is returned, throws an error. -
+
db_nextval sequence-name
Returns the next value for the sequence sequence-name (using a - SQL statement like SELECT - sequence-name.nextval FROM + SQL statement like SELECT + sequence-name.nextval FROM DUAL). If sequence pooling is enabled for the sequence, transparently uses a value from the pool if available to save a round-trip to the database (see Sequence Pooling).
+
db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]
Returns the first column of the result of SQL query - sql. - If sql doesn't return a + sql. + If sql doesn't return a row, returns - default + default (or throws an error if - default is unspecified). Analogous to - database_to_tcl_string and - database_to_tcl_string_or_null. + default is unspecified). Analogous to + database_to_tcl_string and + database_to_tcl_string_or_null. -
+
db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
Returns a Tcl list of the values in the first column of the result of SQL query - sql. - If sql doesn't + sql. + If sql doesn't return any rows, returns an empty list. Analogous to - database_to_tcl_list. + database_to_tcl_list. -
+
db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
Returns a Tcl list, each element of which is a list of all column values - in a row of the result of SQL query sql. If - sql doesn't return any rows, returns an empty list. - (Analogous to database_to_tcl_list_list.) + in a row of the result of SQL query sql. If + sql doesn't return any rows, returns an empty list. + (Analogous to database_to_tcl_list_list.) -
+
db_dml statement-name sql \ [ -bind bind_set_id | -bind bind_value_list ] \ [ -blobs blob_list | -clobs clob_list | -blob_files blob_file_list | -clob_files clob_file_list ] -
Performs the DML or DDL statement sql.
If a length-n list of blobs or clobs is provided, then the SQL +
Performs the DML or DDL statement sql.
If a length-n list of blobs or clobs is provided, then the SQL should return n blobs or clobs into the bind variables - :1, :2, ... :n. - blobs or clobs, if specified, + :1, :2, ... :n. + blobs or clobs, if specified, should be a list of individual BLOBs or CLOBs to insert; - blob_files or clob_files, if + blob_files or clob_files, if specified, should be a list of paths to files containing the data to - insert. Only one of -blobs, -clobs, - -blob_files, and -clob_files may be provided.
Example:
+ insert. Only one of -blobs, -clobs, + -blob_files, and -clob_files may be provided.Example:
-db_dml insert_photos " +db_dml insert_photos " insert photos(photo_id, image, thumbnail_image) values(photo_id_seq.nextval, empty_blob(), empty_blob()) returning image, thumbnail_image into :1, :2 - " -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"] + " -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"]- This inserts a new row into the photos table, with the contents - of the files /var/tmp/the_photo and - /var/tmp/the_thumbnail in the image and - thumbnail columns, respectively. + This inserts a new row into the photos table, with the contents + of the files /var/tmp/the_photo and + /var/tmp/the_thumbnail in the image and + thumbnail columns, respectively.
db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -
Analagous to ns_ora write_clob/write_blob/blob_get_file. +
Analagous to ns_ora write_clob/write_blob/blob_get_file. -
+
db_release_unused_handles -
Releases any allocated, unused database handles.
+
Releases any allocated, unused database handles.
db_transaction code_block [ on_error { code_block } ] -
Executes code_block transactionally. Nested - transactions are supported (end transaction is transparently - ns_db dml'ed when the outermost transaction completes). The - db_abort_transaction command can be used to abort all levels of - transactions. It is possible to specify an optional on_error +
Executes code_block transactionally. Nested + transactions are supported (end transaction is transparently + ns_db dml'ed when the outermost transaction completes). The + db_abort_transaction command can be used to abort all levels of + transactions. It is possible to specify an optional on_error code block that will be executed if some code in code_block throws - an exception. The variable errmsg will be bound in that scope. - If there is no on_error code, any errors will be propagated.
Example:
+ an exception. The variable errmsg will be bound in that scope. + If there is no on_error code, any errors will be propagated.Example:
proc replace_the_foo { col } { db_transaction { - db_dml "delete from foo" - db_dml "insert into foo(col) values($col)" + db_dml "delete from foo" + db_dml "insert into foo(col) values($col)" } } proc print_the_foo {} { - doc_body_append "foo is [db_string "select col from foo"]<br>\n" + doc_body_append "foo is [db_string "select col from foo"]<br>\n" } replace_the_foo 8 -print_the_foo ; # Writes out "foo is 8" +print_the_foo ; # Writes out "foo is 8" db_transaction { replace_the_foo 14 - print_the_foo ; # Writes out "foo is 14" - db_dml "insert into some_other_table(col) values(999)" + print_the_foo ; # Writes out "foo is 14" + db_dml "insert into some_other_table(col) values(999)" ... db_abort_transaction } on_error { - doc_body_append "Error in transaction: $errmsg" + doc_body_append "Error in transaction: $errmsg" } -print_the_foo ; # Writes out "foo is 8" +print_the_foo ; # Writes out "foo is 8" -
+
db_resultrows
Returns the number of rows affected or returned by the previous statement. -
+
db_with_handle var code_block -
Places a database handle into the variable var and - executes code_block. This is useful when you don't - want to have to use the new API (db_foreach, - db_1row, etc.), but need to use database handles explicitly.
Example:
+
Places a database handle into the variable var and + executes code_block. This is useful when you don't + want to have to use the new API (db_foreach, + db_1row, etc.), but need to use database handles explicitly.
Example:
proc lookup_the_foo { foo } {
db_with_handle db {
- return [db_string unused "select ..."]
+ return [db_string unused "select ..."]
}
}
db_with_handle db {
# Now there's a database handle in $db.
- set selection [ns_db select $db "select foo from bar"]
+ set selection [ns_db select $db "select foo from bar"]
while { [ns_db getrow $db $selection] } {
set_variables_after_query
@@ -651,38 +650,38 @@
db_nullify_empty_string string
For true SQL purists, we provide the convenience function - db_nullify_empty_string, which returns - [db_null] if its string argument is the empty string + db_nullify_empty_string, which returns + [db_null] if its string argument is the empty string and can be used to encapsulate another Oracle quirk:
-set baz ""
+set baz ""
# Clean out the foo table
#
-db_dml unused "delete from foo"
+db_dml unused "delete from foo"
-db_dml unused "insert into foo(baz) values('$baz')"
+db_dml unused "insert into foo(baz) values('$baz')"
-set n_rows [db_string unused "select count(*) from foo where baz is null"]
+set n_rows [db_string unused "select count(*) from foo where baz is null"]
#
-# $n_rows is 1; in effect, the "baz is null" criterion is matching
+# $n_rows is 1; in effect, the "baz is null" criterion is matching
# the empty string we just inserted (because of Oracle's coercion
# quirk)
- To balance out this asymmetry, you can explicitly set baz to - null by writing: + To balance out this asymmetry, you can explicitly set baz to + null by writing:
-db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
+db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
-