Feature #8974 - Temporary Tables in Packages

doc/sql.extensions/README.name_resolution.md

@@ -7,8 +7,8 @@ search path. The ambiguity arises between:
 - `<schema>.<object>` (a schema and its object)
 - `<package>.<object>` (a package and its object)
 
-This document focuses on name resolution rules for tables, views, procedures, and functions within queries and
-code blocks.
+This document focuses on name resolution rules for tables, views, procedures, and functions within queries,
+code blocks, and `COMMENT ON`.
 
 ## Scope specifier (`%`)
 
@@ -36,6 +36,13 @@ select rdb$time_zone_util%package.database_version()
 
 select *
     from rdb$time_zone_util%package.transitions('America/Sao_Paulo', timestamp '2017-01-01', timestamp '2019-01-01');
+
+select *
+    from pkg_ltt%package.t_pub;
+
+comment on table pkg_ltt%package.t_pub is 'Public packaged temporary table';
+
+comment on column pkg_ltt%package.t_pub.id is 'Column comment through %package';
 ```
 
 ## Detailed name resolution rules

doc/sql.extensions/README.packaged_temporary_tables.md

@@ -0,0 +1,217 @@
+# Packaged Temporary Tables (FB 6.0)
+
+Firebird 6.0 supports declaring temporary tables in SQL packages.
+
+Internally, they are stored as package-owned persistent temporary table metadata, identified through `RDB$PACKAGE_NAME`.
+Their data remains temporary: transaction-local for `ON COMMIT DELETE ROWS` and connection-local for
+`ON COMMIT PRESERVE ROWS`.
+
+## Syntax
+
+Packaged temporary tables can be used in package header and body.
+
+```sql
+CREATE PACKAGE <package_name>
+AS
+BEGIN
+    [{<package_item> ;}...]
+END
+
+<package_item> ::=
+    <package_temporary_table_declaration> |
+    <package_procedure_declaration> |
+    <package_function_declaration> |
+	<package_constant_declaration>
+
+<package_temporary_table_declaration> ::=
+    TEMPORARY TABLE <table_name>
+    (
+        <column_definition> [, ...]
+    )
+    [ON COMMIT {DELETE | PRESERVE} ROWS]
+    [{[UNIQUE] [ASC | DESC] INDEX <index_name> (<column_name>)}...]
+```
+
+```sql
+CREATE PACKAGE BODY <package_name>
+AS
+BEGIN
+    [{<package_item> ;}...]
+END
+
+<package_body_item> ::=
+    <package_temporary_table_declaration> |
+    <package_procedure_definition> |
+    <package_function_definition> |
+	<package_constant_declaration>
+```
+
+## Semantics
+
+- `ON COMMIT DELETE ROWS` (default): rows are transaction-local and cleared at transaction end.
+- `ON COMMIT PRESERVE ROWS`: rows are connection-local and preserved across transactions in the same attachment.
+
+The table definition is part of package metadata and is persistent like other package members; table data remains
+temporary.
+
+## Visibility and Name Resolution
+
+Visibility depends on where the table is declared:
+
+- Tables declared in `CREATE PACKAGE` (header) are public package members.
+- Tables declared in `CREATE PACKAGE BODY` are private to that package body.
+- Unqualified references to a matching declared table name inside package routines resolve to the package table.
+
+External SQL access rules:
+
+- Header tables can be accessed externally as `package_name.table_name` or `package_name%package.table_name`
+  (for example, `pkg.t_pub` or `pkg%package.t_pub`).
+- Schema-qualified packaged table access uses the three-part form `{schema_name}.package_name.table_name`.
+- Body tables cannot be accessed externally and are only valid inside routines of the same package body, including
+  when using `%package`.
+
+Permissions:
+
+- Packaged temporary table permissions are attached to the package, not to individual packaged tables.
+- Direct access to public header tables requires the appropriate package privilege for the requested operation, such
+  as `SELECT`, `INSERT`, `UPDATE` or `DELETE`.
+- Private body tables cannot be made externally accessible with package grants.
+- If the package is created in a non-public schema, the caller also needs `USAGE` on that schema.
+
+Example:
+
+```sql
+grant select, insert on package pkg to user some_user;
+```
+
+Index DDL rules:
+
+- Packaged temporary table indexes must be declared inline in `TEMPORARY TABLE`.
+- Standalone index DDL commands are not allowed for packaged tables:
+  `CREATE INDEX`, `ALTER INDEX`, `DROP INDEX`, `SET STATISTICS INDEX`.
+
+`COMMENT ON` support:
+
+- `COMMENT ON TABLE package_name.table_name IS ...` is supported for packaged temporary tables.
+- `COMMENT ON TABLE package_name%package.table_name IS ...` is also supported.
+- `COMMENT ON COLUMN package_name.table_name.column_name IS ...` is supported for columns of packaged
+  temporary tables.
+- `COMMENT ON COLUMN package_name%package.table_name.column_name IS ...` is also supported.
+- This applies to both header-declared public tables and body-declared private tables.
+- Descriptions are stored in the regular metadata fields
+  `RDB$RELATIONS.RDB$DESCRIPTION` and `RDB$RELATION_FIELDS.RDB$DESCRIPTION`.
+
+## Name Isolation
+
+The table names are isolated by package context.
+
+- Different packages may declare tables with the same name.
+- A package table name may also match a regular table name in the same schema.
+
+Resolution inside package routines prefers the package-local declaration.
+
+## Dependencies and DDL lifecycle
+
+`DROP PACKAGE` removes package body/header dependencies and package members (routines and declared tables) in package
+scope.
+
+`ALTER PACKAGE` and `CREATE OR ALTER PACKAGE` recreate packaged declared local temporary tables that belong to the
+package header.
+Existing private packaged tables from the body definition are dropped.
+
+`RECREATE PACKAGE BODY` and `CREATE OR ALTER PACKAGE BODY` recreate packaged declared local temporary tables that
+belong to the package body.
+Existing private packaged tables from the previous body definition are dropped before the new body tables are created.
+
+## System metadata changes
+
+Packaged temporary tables add package ownership and visibility information to system metadata.
+Tools that inspect metadata should use these columns when present.
+
+| Table                | Column             | Meaning                                                           |
+|----------------------|--------------------|-------------------------------------------------------------------|
+| `RDB$RELATIONS`      | `RDB$PACKAGE_NAME` | Owning package of the declared temporary table                    |
+| `RDB$RELATIONS`      | `RDB$PRIVATE_FLAG` | `PUBLIC` (`0`) for header tables, `PRIVATE` (`1`) for body tables |
+| `RDB$RELATION_FIELDS`| `RDB$PACKAGE_NAME` | Owning package of the declared temporary table columns            |
+| `RDB$INDICES`        | `RDB$PACKAGE_NAME` | Owning package of inline indexes declared for packaged tables     |
+| `RDB$INDEX_SEGMENTS` | `RDB$PACKAGE_NAME` | Owning package of the packaged table index segments               |
+| `MON$TABLE_STATS`    | `MON$PACKAGE_NAME` | Owning package reported in runtime table statistics               |
+
+In monitoring, packaged temporary tables are reported as `GLOBAL TEMPORARY` in `MON$TABLE_STATS.MON$TABLE_TYPE`.
+
+## Example
+
+```sql
+set term !;
+
+recreate package pkg
+as
+begin
+    temporary table t_pub(
+        id integer
+    ) on commit preserve rows
+      index idx_t_pub_id (id);
+
+    procedure p1(n integer);
+    procedure p2 returns (n integer);
+end!
+
+create package body pkg
+as
+begin
+    temporary table t_priv(
+        id integer
+    ) on commit preserve rows
+      unique index uq_t_priv_id (id);
+
+    procedure p1(n integer)
+    as
+    begin
+        insert into t_pub(id) values (:n);
+        insert into t_priv(id) values (:n);
+    end
+
+    procedure p2 returns (n integer)
+    as
+    begin
+        for select id from t_pub into :n do
+            suspend;
+    end
+end!
+
+set term ;!
+
+-- use package routines
+execute procedure pkg.p1(10);
+select * from pkg.p2;
+
+-- header-declared table: allowed
+select * from pkg.t_pub;
+select * from pkg%package.t_pub;
+
+-- body-declared table: not allowed
+-- select * from pkg.t_priv;
+-- select * from pkg%package.t_priv;
+
+comment on table pkg.t_pub is 'Public packaged temporary table';
+comment on column pkg.t_pub.id is 'Identifier in public packaged temporary table';
+comment on table pkg.t_priv is 'Private packaged temporary table';
+comment on column pkg.t_priv.id is 'Identifier in private packaged temporary table';
+comment on table pkg%package.t_pub is 'Public packaged temporary table via %package';
+comment on column pkg%package.t_pub.id is 'Identifier via %package';
+comment on table pkg%package.t_priv is 'Private packaged temporary table via %package';
+comment on column pkg%package.t_priv.id is 'Identifier in private table via %package';
+
+-- not allowed for packaged tables:
+-- create index idx_cmd on pkg.t_pub(id);
+-- alter index idx_t_pub_id active;
+-- drop index idx_t_pub_id;
+```
+
+## Notes
+
+- This feature is distinct from SQL-created local temporary tables (`CREATE LOCAL TEMPORARY TABLE ...`), which are
+  attachment-private DDL objects.
+- Packaged temporary tables are not attachment-private created LTTs. They use persistent temporary-table metadata
+  associated with the package through `RDB$PACKAGE_NAME`.
+- Packaged temporary tables follow package compilation, visibility, and dependency rules.

src/auth/SecurityDatabase/LegacyServer.cpp

@@ -66,6 +66,7 @@ const UCHAR PWD_REQUEST[] =
 	blr_rse, 1,
 	blr_relation3,
 		14, 'P', 'L', 'G', '$', 'L', 'E', 'G', 'A', 'C', 'Y', '_', 'S', 'E', 'C',	// PLG_LEGACY_SEC_SCHEMA
+		0,
 		9, 'P', 'L', 'G', '$', 'U', 'S', 'E', 'R', 'S',
 		0,
 		0,

src/burp/backup.epp

@@ -425,6 +425,9 @@ int BACKUP_backup(const TEXT* dbb_file, const TEXT* file_name)
 		if (relation->rel_name.schema.hasData())
 			put_text(att_relation_schema_name, relation->rel_name.schema);
 
+		if (relation->rel_name.package.hasData())
+			put_text(att_relation_package_name, relation->rel_name.package);
+
 		put_text(att_relation_name, relation->rel_name.object);
 
 		put(tdgbl, att_end);
@@ -681,6 +684,7 @@ burp_fld* get_fields( burp_rel* relation)
 			X.RDB$FIELD_SOURCE_SCHEMA_NAME EQUIV Y.RDB$SCHEMA_NAME AND
 			X.RDB$FIELD_SOURCE = Y.RDB$FIELD_NAME AND
 			X.RDB$SCHEMA_NAME EQUIV NULLIF(relation->rel_name.schema.c_str(), '') AND
+			X.RDB$PACKAGE_NAME EQUIV NULLIF(relation->rel_name.package.c_str(), '') AND
 			X.RDB$RELATION_NAME EQ relation->rel_name.object.c_str()
 		{
 			field = (burp_fld*) BURP_alloc_zero(sizeof(burp_fld));
@@ -1667,6 +1671,7 @@ void put_index( burp_rel* relation)
 		FOR (REQUEST_HANDLE tdgbl->handles_put_index_req_handle1)
 			X IN RDB$INDICES WITH
 			X.RDB$SCHEMA_NAME EQUIV NULLIF(relation->rel_name.schema.c_str(), '') AND
+			X.RDB$PACKAGE_NAME EQUIV NULLIF(relation->rel_name.package.c_str(), '') AND
 			X.RDB$RELATION_NAME EQ relation->rel_name.object.c_str() AND
 			X.RDB$INDEX_NAME NOT STARTING TEMP_DEPEND
 		{
@@ -1676,8 +1681,10 @@ void put_index( burp_rel* relation)
 				RFR IN RDB$RELATION_FIELDS WITH
 				I_S.RDB$FIELD_NAME = RFR.RDB$FIELD_NAME AND
 				I_S.RDB$SCHEMA_NAME EQUIV RFR.RDB$SCHEMA_NAME AND
+				I_S.RDB$PACKAGE_NAME EQUIV RFR.RDB$PACKAGE_NAME AND
 				I_S.RDB$INDEX_NAME = X.RDB$INDEX_NAME AND
 				RFR.RDB$SCHEMA_NAME EQUIV NULLIF(relation->rel_name.schema.c_str(), '') AND
+				RFR.RDB$PACKAGE_NAME EQUIV NULLIF(relation->rel_name.package.c_str(), '') AND
 				RFR.RDB$RELATION_NAME = relation->rel_name.object.c_str()
 			{
 				count++;
@@ -1695,7 +1702,8 @@ void put_index( burp_rel* relation)
 
 			put(tdgbl, rec_index);
 			PUT_TEXT(att_index_name, X.RDB$INDEX_NAME);
-			BURP_verbose(151, QualifiedMetaString(X.RDB$INDEX_NAME, relation->rel_name.schema).toQuotedString());
+			BURP_verbose(151, QualifiedMetaString(
+				X.RDB$INDEX_NAME, relation->rel_name.schema, relation->rel_name.package).toQuotedString());
 			// msg 151 writing index %s
 
 			put_int32 (att_segment_count, X.RDB$SEGMENT_COUNT);
@@ -1705,6 +1713,7 @@ void put_index( burp_rel* relation)
 			FOR (REQUEST_HANDLE tdgbl->handles_put_index_req_handle5)
 				Y IN RDB$INDEX_SEGMENTS WITH
 				Y.RDB$SCHEMA_NAME EQUIV NULLIF(relation->rel_name.schema.c_str(), '') AND
+				Y.RDB$PACKAGE_NAME EQUIV NULLIF(relation->rel_name.package.c_str(), '') AND
 				Y.RDB$INDEX_NAME EQ X.RDB$INDEX_NAME
 				SORTED BY Y.RDB$FIELD_POSITION
 			{
@@ -4057,6 +4066,7 @@ void write_rel_constraints()
 		X IN RDB$RELATION_CONSTRAINTS CROSS
 		REL IN RDB$RELATIONS
 		WITH REL.RDB$SCHEMA_NAME EQUIV X.RDB$SCHEMA_NAME AND
+			 REL.RDB$PACKAGE_NAME MISSING AND
 			 REL.RDB$RELATION_NAME EQ X.RDB$RELATION_NAME AND
 			 (REL.RDB$SYSTEM_FLAG MISSING OR REL.RDB$SYSTEM_FLAG NE 1)
 	{
@@ -4132,6 +4142,15 @@ void write_relations()
 				name.schema = X.RDB$SCHEMA_NAME;
 			}
 
+			if (!X.RDB$PACKAGE_NAME.NULL)
+			{
+				PUT_TEXT(att_relation_package_name, X.RDB$PACKAGE_NAME);
+				name.package = X.RDB$PACKAGE_NAME;
+			}
+
+			if (!X.RDB$PRIVATE_FLAG.NULL)
+				put_int32(att_relation_private_flag, X.RDB$PRIVATE_FLAG);
+
 			PUT_TEXT(att_relation_name, X.RDB$RELATION_NAME);
 			name.object = X.RDB$RELATION_NAME;
 

src/burp/burp.h

@@ -213,6 +213,15 @@ Version 11: FB4.0.
 
 Version 12: FB6.0.
 			Schemas.
+
+			Packaged constants.
+
+			Packaged tables:
+			RDB$RELATIONS.RDB$PACKAGE_NAME,
+			RDB$RELATIONS.RDB$PRIVATE_FLAG,
+			RDB$RELATION_FIELDSS.RDB$PACKAGE_NAME,
+			RDB$INDICES.RDB$PACKAGE_NAME and
+			RDB$INDEX_SEGMENTS.RDB$PACKAGE_NAME.
 */
 
 inline constexpr int ATT_BACKUP_FORMAT = 12;
@@ -292,6 +301,8 @@ enum att_type {
 	att_relation_sql_security_deprecated,	// can be removed later
 	att_relation_sql_security,
 	att_relation_schema_name,
+	att_relation_package_name,
+	att_relation_private_flag,
 
 	// Field attributes (used for both global and local fields)