50 DBMS_DBFS_SFS

The DBMS_DBFS_SFS package provides an interface to operate a SecureFile-based store (SFS) for the content interface described in the DBMS_DBFS_CONTENT package.

Using DBMS_DBFS_SFS

Overview
Security Model
Constants

Overview

The DBMS_DBFS_SFS package is a sample implementation of a package that implements and extends the DBMS_DBFS_CONTENT_SPI interface. It provides a POSIX-compliant file system stored in the RDBMS.

Security Model

The DBMS_DBFS_SFS package runs with AUTHID CURRENT_USER.

Constants

The DBMS_DBFS_SFS package uses the constants shown in following tables:

DBMS_DBFS_SFS Constants - Compression Levels
DBMS_DBFS_SFS Constants - Used by the encryption Parameter
DBMS_DBFS_SFS Constants - Used by the npartitions Parameter
DBMS_DBFS_SFS Constants - Used by the partition_key Parameter

Table 50-1 DBMS_DBFS_SFS Constants - Compression Levels

Constant	Type	Value	Description
`COMPRESSION_DEFAULT`	`VARCHAR2(32)`	`''`	Use the default SecureFile compression level
`COMPRESSION_LOW`	`VARCHAR2(32)`	`'LOW'`	Use compression level `'LOW'`
`COMPRESSION_MEDIUM`	`VARCHAR2(32)`	`'MEDIUM'`	Use compression level `'MEDIUM'`
`COMPRESSION_HIGH`	`VARCHAR2(32)`	`'HIGH'`	Use compression level `'HIGH'`

Table 50-2 DBMS_DBFS_SFS Constants - Used by the encryption Parameter

Constant	Type	Value	Description
`ENCRYPTION_DEFAULT`	`VARCHAR2(32)`	`''`	Use the default SecureFile encryption algorithm
`ENCRYPTION_3DES168`	`VARCHAR2(32)`	`'3DES168'`	Use encryption 3DES 168 bit
`ENCRYPTION_AES128`	`VARCHAR2(32)`	`'AES128'`	Use encryption AES 128 bit
`ENCRYPTION_AES192`	`VARCHAR2(32)`	`'AES192'`	Use encryption AES 192 bit
`ENCRYPTION_AES256`	`VARCHAR2(32)`	`'AES256'`	Use encryption AES 256 bit

Table 50-3 DBMS_DBFS_SFS Constants - Used by the npartitions Parameter

Constant	Type	Value	Description
`DEFAULT_PARTITIONS`	`INTEGER`	`16`	Default to 16 partitions

Table 50-4 DBMS_DBFS_SFS Constants - Used by the partition_key Parameter

Constant	Type	Value	Description
`PARTITION_BY_ITEM`	`INTEGER`	`1`	Use a hash of the item name for the partition key
`PARTITION_BY_PATH`	`INTEGER`	`2`	Use a hash of the path name for the partition key
`PARTITION_BY_GUID`	`INTEGER`	`3`	Use a hash of the GUID as the partition key

Summary of DBMS_DBFS_SFS Subprograms

Table 50-5 DBMS_DBFS_SFS Package Subprograms

Subprogram	Description
CREATEFILESYSTEM Procedure	Creates a file system store
CREATESTORE Procedure	Creates a new DBFS SFS store
DROPFILESYSTEM Procedures	Drops the DBFS SFS store
INITFS Procedure	Initializes a POSIX file system store

CREATEFILESYSTEM Procedure

This procedure creates a file system store.

Syntax

DBMS_DBFS_SFS.CREATEFILESYSTEM (
   store_name         IN     VARCHAR2,
   schema_name        IN     VARCHAR2    DEFAULT NULL,
   tbl_name           IN     VARCHAR2    DEFAULT NULL,
   tbl_tbs            IN     VARCHAR2    DEFAULT NULL,
   lob_tbs            IN     VARCHAR2    DEFAULT NULL,
   use_bf             IN     BOOLEAN     DEFAULT FALSE,
   properties         IN     DBMS_DBFS_CONTENT_PROPERTIES_T DEFAULT NULL,
   create_only        IN     BOOLEAN     FALSE,
   use_objects        IN     BOOLEAN     DEFAULT FALSE,
   with_grants        IN     BOOLEAN     DEFAULT FALSE,
   do_dedup           IN     BOOLEAN     DEFAULT FALSE,
   do_compress        IN     BOOLEAN     DEFAULT FALSE
   compression        IN     VARCHAR2    DEFAULT COMPRESSION_DEFAULT,
   do_encrypt         IN     BOOLEAN     DEFAULT FALSE,
   encryption         IN     VARCHAR2    DEFAULT ENCRYPTION_DEFAULT,
   do_partition       IN     BOOLEAN     DEFAULT FALSE,
   npartitions        IN     NUMBER      DEFAULTDEFAULT_PARTITIONS,
   partition_key      IN     NUMBER      DEFAULT PARTITION_BY_ITEM,
   partition_guidi    IN     BOOLEAN     DEFAULT FALSE,
   partition_pathi    IN     BOOLEAN     DEFAULT FALSE,
   partition_prop     IN     BOOLEAN     DEFAULT TRUE);

Parameters

Table 50-6 CREATEFILESYSTEM Procedure Parameters

Parameter	Description
`store_name`	Name of store
`schema_name`	Schema for the store, defaulting to the current schema
`tbl_name`	Table for store entries. If not specified, an internally generated name is used.
`tbl_tb`	Tablespace for the store, defaulting to the schema's default tablespace
`lob_tbs`	Tablespace in which to create the LOB segment. It defaults to the user's default tablespace.
`use_bf`	If `TRUE`, a BasicFile `LOB` is used; otherwise a SecureFile `LOB` is used.
`properties`	Table of (name, value, typecode) tuples used to configure the store properties. Currently no such properties are defined or used.
`create_only`	If `TRUE`, the file system is created, but not registered with the current user
`use_objects`	If `TRUE`, a single base-table with an object-type column (using a nested table) is created to backup the new file system. Otherwise, a pair of (parent, child) tables is used to backup the file system. In both cases, the object type nested table or the child table is used only for user-defined properties.
`with_grants`	If `TRUE`, DML and query access permissions are granted to the `DBFS_ROLE` as part of creating the file system. Otherwise, explicit grants (or existing permissions) are required to access the file system.
`do_dedup`	If `TRUE`, do deduplication the underlying SecureFile column
`do_compress`	If `TRUE`, do compression the underlying SecureFile column
`compression`	Compression algorithm to use (see DBMS_DBFS_SFS Constants - Compression Levels)
`do_encrypt`	If `TRUE`, encrypt the underlying SecureFile column
`encryption`	encryption algorithm to use (see DBMS_DBFS_SFS Constants - Used by the encryption Parameter)
`do_partition`	If `TRUE`, partition the table used for storage
`npartitions`	Number of partitions to create for the table (see DBMS_DBFS_SFS Constants - Used by the npartitions Parameter).
`partition_key`	How to partition the table: by item name, by path name, or by GUID (see DBMS_DBFS_SFS Constants - Used by the partition_key Parameter).
`partition_guidi`	If `TRUE`, build an index on GUID
`partition_pathi`	If `TRUE`, build an index on path name
`partition_prop`	If `TRUE`, partition the properties table

Usage Notes

The procedure executes like a DDL in that it auto-commits before and after its execution.

CREATESTORE Procedure

This procedure creates a new DBFS SFS store owned by the invoking session user.

Syntax

DBMS_DBFS_SFS.CREATESTORE  (
   store_name     IN     VARCHAR2,
   tbl_name       IN     VARCHAR2  DEFAULT NULL,
   tbs_name       in     VARCHAR2  DEFAULT NULL,
   use_bf         in     BOOLEAN   DEFAULT FALSE,
   stgopts        in     VARCHAR2 DEFAULT '');

Parameters

Table 50-7 CREATESTORE Procedure Parameters

Parameter	Description
`store_name`	Name of store
`store_type`	`STORETYPE_TAPE` or `STORETYPE_AMAZONS3`
`tbl_name`	Placeholder for the store content cached in database
`tbs_name`	Named tablespace
`use_bf`	If `TRUE`, a BasicFile `LOB` is used; otherwise a SecureFile `LOB` is used.
`stgopts`	Currently non-operational, reserved for future use

DROPFILESYSTEM Procedures

This procedure drops the DBFS SFS store, purging all dictionary information associated with the store, and dropping the underlying file system table.

Syntax

DBMS_DBFS_SFS.DROPFILESYSTEM  (
   schema_name    IN      VARCHAR2 DEFAULT NULL,
   tbl_name       IN      INTEGER);

DBMS_DBFS_SFS.DROPFILESYSTEM  (
   store_name     IN      VARCHAR2);

Parameters

Table 50-8 DROPFILESYSTEM Procedure Parameters

Parameter	Description
`schema_name`	Name of schema
`tbl_name`	Name of tablespace
`store_name`	Name of store path

Usage Notes

If the specified store table is registered by the current user, it will be unregistered from the content interface described in the DBMS_DBFS_CONTENT package and the POSIX metadata tables.
Subsequent to unregistration, an attempt will be made to store table(s). This operation may fail if other users are currently using this store table.
The user attempting a drop of the tables underlying the store must actually have the privileges to complete the drop operation (either as the owner of the tables, or as a sufficiently privileged user for cross-schema operations).
The procedure executes like a DDL in that it auto-commits before and after its execution.

INITFS Procedure

This procedure initialize a POSIX file system store. The table associated with the POSIX file system store store_name is truncated and reinitialized with a single "root" directory entry.

Syntax

DBMS_DBFS_SFS.INITFS (
   store_name     IN      VARCHAR2);

Parameters

Table 50-9 INITFS Procedure Parameters

Parameter	Description
`store_name`	Name of store

Usage Notes

The procedure executes like a DDL in that it auto-commits before and after its execution.