75 DBMS_FS

The DBMS_FS package for performing operations on an Oracle file system (make, mount, unmount and destroy operations) in an Oracle database.

This chapter contains the following topics:

75.1 DBMS_FS Overview

The DBMS_FS package contains Oracle file system (OFS) procedures that you can use to create, mount, unmount, and destroy an Oracle file system.

Starting 19c release, the file systems are supported by PDB. Oracle Database supports maximum 5 file systems per PDB and 1000 file systems in total.

The DBMS_FS package enables applications to access database objects from a universal client such as an NFS server. This feature interfaces with Oracle SecureFiles to provide the file system access.

See Also:

Oracle Database SecureFiles and Large Objects Developer's Guide for a detailed description of managing an NFS server in Oracle Database

75.2 DBMS_FS Security Model

You must have the SYSDBA administrative privilege to use the DBMS_FS package.

The operations that you perform using the DBMS_FS package are equivalent to the file system operations that are performed in an operating system by the root user. Access to the individual file system that is created and mounted by this package is enforced using Access Control Lists (ACLs) and the permissions on the mounted directories to the operating system user.

75.3 Summary of DBMS_FS Subprograms

This table lists the DBMS_FS subprograms and briefly describes them.

Table 75-1 DBMS_FS Subprograms

Subprogram Description

DESTROY_ORACLE_FS Procedure

Destroys an Oracle file system, using the fstype and of name fsname

MAKE_ORACLE_FS Procedure

Creates a file system of type specified by fstype and of name fsname

MOUNT_ORACLE_FS Procedure

Mounts an Oracle file system on the specified mount point

UNMOUNT_ORACLE_FS Procedure

Unmounts an Oracle file system on the specified mount point

75.3.1 DESTROY_ORACLE_FS Procedure

This procedure destroys an Oracle file system and then frees the resources that were associated with it.

Syntax

DBMS_FS.DESTROY_ORACLE_FS (
   fstype      IN VARCHAR2,
   fsname      IN VARCHAR2);

Parameters

Table 75-2 DBMS_FS Parameters

Parameter Description

fstype

File system type. Oracle File System (OFS) and Database File System (DBFS) are supported.

fsname

Name of the file system

Usage Notes

  • You can find information about the currently mounted file systems by querying the V$OFSMOUNT dynamic view.

  • For more information about the file system types, see the fstype description in MAKE_ORACLE_FS Procedure.

  • Before you run the DBMS_FS.DESTROY_ORACLE_FS procedure, you must unmount the file system by using the DBMS_FS.UNMOUNT_ORACLE_FS procedure.

  • After you run DBMS_FS.DESTROY_ORACLE_FS, Oracle Database destroys the file system and frees the associated resources.

Example

This example shows how to destroy an DBFS file system:

BEGIN
 DBMS_FS.DESTROY_ORACLE_FS (
  fstype           => 'dbfs',
  fsname           => 'dbfs_fs1');
END;
/

75.3.2 MAKE_ORACLE_FS Procedure

This procedure creates a new file system of type DBFS, on top of an existing Oracle tablespace or other database object.

Syntax

DBMS_FS.MAKE_ORACLE_FS (
   fstype      IN VARCHAR2,                             
   fsname      IN VARCHAR2,                             
   fsoptions   IN VARCHAR2);

Parameters

Table 75-3 DBMS_FS Parameters

Parameter Description

fstype 

File system type. Enter one of the following values:
  • ofs—to create an Oracle File System
  • dbfs—to create a Database File System

fsname 

Name of the file system. Enter a string no longer than 256 characters, using alphanumeric characters.

fsoptions 

Specify an existing tablespace to use for the Oracle file system, using the following format:

"tablespace=tablespace_name"

Usage Notes

  • If you want to create a database file system (DBFS), then you must run the dbfs_create_filesystem.sql script, which in turn calls the dbfs_create_filesystem_advanced.sql script. By default, this script is in the $ORACLE_HOME/rdbms/admin directory. When you run this script, provide the name of an existing tablespace and a name for the file system that will be stored in the database. The size of the file system will be the same as the table size. For example, to create a file system in the dbfs_ts tablespace, in the file system dbfs_tab:

    @/$ORACLE_HOME/rdbms/admin/dbfs_create_filesystem.sql dbfs_ts dbfs_tab

    After you run this script, you can use the other procedures in the DBMS_FS package to mount, unmount, and destroy the file system.

    Note:

    Staring Oracle Database 19.3.1.0 release, the DBMS_FS.MAKE_ORACLE_FS is used to create a DBFS filesystem; hence no auxiliary SQL script is needed to create a DBFS filesystem.
  • Running the DBMS_FS.MAKE_ORACLE_FS procedure on the database instance is equivalent to running the mkfs command by root in an operating system.

  • The tablespace that you specified in the fsoptions parameter must already exist before you execute the DBMS_FS.MAKE_ORACLE_FS procedure. To find existing tablespaces, query the DBA_TABLESPACES data dictionary view.

  • The size of the file system is the same size as this tablespace.

Example

This example shows how to create an DBFS file system:

BEGIN
 DBMS_FS.MAKE_ORACLE_FS (
  fstype           => 'dbfs',
  fsname           => 'dbfs_fs1',
  mount_options    => 'TABLESPACE=dbfs_fs1_tbspc');
END;
/

75.3.3 MOUNT_ORACLE_FS Procedure

This procedure mounts an Oracle file system on the specified mount point.

Syntax

DBMS_FS.MOUNT_ORACLE_FS (
  fstype           IN VARCHAR2,                              
  fsname           IN VARCHAR2,                              
  mount_point      IN VARCHAR2,                              
  mount_options    IN VARCHAR2); 

Parameters

Table 75-4 MOUNT_ORACLE_FS Procedure Parameters

Parameter Description

fstype

File system type. Oracle File System (OFS) and Database File System (DBFS) are supported.

fsname

Name of the file system. Enter a string no longer than 256 characters, using alpha numeric characters.

mount_point

Local directory where the file system should be mounted. This directory must already exist. Enter an absolute path. The maximum number of mount points that you can create is 5 mount points per PDB and 1000 mount points per instance.

mount_options

Comma-separated mount options, listed in Table 75-5.

Usage Notes

Table 75-5 Supported Mount Options for the MOUNT_ORACLE_FS procedure

Mount Option Usage Description
default_permissions Enables permission check and restrict access based on file mode. This option is useful with the allow_other mount option.
allow_other Allows other users apart from the operating system user that did the mount can access the files. This will be used in conjunction with permission checks in determining the file access. This option requires setting the user_allow_other parameter in the /etc/fuse.conf configuration file on Linux.
max_read Maximum size of the read operation. No maximum size is set by default.
max_write Maximum write size in a single request. The default is 128K.
direct_io Indicates to the operating system kernel not use file system cache.
nopersist Does not store the mount options for use in next instance startup.
ro Mounts the file system in read-only mode. Files cannot be modified.
rw Mounts the file system as read-write. This is the default.
nosuid Specifies that the file system cannot contain set userid files.
suid Specifies that the file system can contain set userid files. This is the default.

Note:

The following options are exclusive options and cannot be used together:
  • nopersist/persist
  • ro/rw
  • nosuid/suid

Usage Notes

  • This procedure makes the files system visible in the local database instance.

  • For more information about the file system types, see the fstype description in MAKE_ORACLE_FS Procedure.

  • You can find information about currently mounted file systems by querying the V$OFSMOUNT dynamic view.

  • Run the DBMS_FS.MOUNT_ORACLE_FS procedure on a file system that has already been created with DBMS_FS.MAKE_ORACLE_FS in the local computer node where the Oracle database instance is running. You cannot run this procedure on file systems that were created outside of Oracle Database.

Example

BEGIN
 DBMS_FS.MOUNT_ORACLE_FS (
  fstype           => 'dbfs',                              
  fsname           => 'dbfs_fs1',                              
  mount_point      => '/oracle/dbfs/testfs',                              
  mount_options    => 'default_permissions, allow_other, persist'); 
END;

75.3.4 UNMOUNT_ORACLE_FS Procedure

This procedure unmounts an Oracle file system on the specified mount point.

Syntax

DBMS_FS.UNMOUNT_ORACLE_FS (
  fsname             IN VARCHAR2,                              
  mount_point        IN VARCHAR2,                              
  unmount_options    IN VARCHAR2); 

Table 75-6 UNMOUNT_ORACLE_FS Procedure Parameters

Parameter Description

fsname

Name of the file system

mount_point

Local directory where the file system had been mounted. Enter an absolute path.

unmount_options

Optionally, enter force to unmount the file system forcibly. This setting prevents new requests from being sent to the file system. All pending requests on the file system are either completed or cancelled.

If you omit this setting, then attempts to unmount a busy file system cause an EBUSY error.

Usage Notes

  • Before you unmount the file system, ensure that all applications that use this file system are shut down. Also ensure that no processes refernce the mounting file system.

  • You can find information about the currently mounted file systems by querying the V$OFSMOUNT dynamic view.

  • For more information about the file system types, see the fstype description in MAKE_ORACLE_FS Procedure.

  • When an Oracle instance is shut down in normal immediate mode, then all the mounted file systems are automatically unmounted.

  • If a file system is mounted with the MOUNT_ORACLE_FS procedure with the persist option, it will be automatically mounted again when the database instance starts or the PDB is plugged. If this file system is unmounted by executing DBMS_FS.UNMOUNT_ORACLE_FS, it will remain unmounted even if the persist option was used to mount it.

  • If you perform a SHUTDOWN ABORT, then the file system may still show as mounted but not accessible. In this case, you must unmount the system manually by calling  unmount command at the operating system level or fusermount procedure on Linux systems.

  • You can export the local mount point of an Oracle file system to point to the remote system, and then NFS mount the file system from the remote system by using the operating system mount command. The DBMS_FS.MOUNT_ORACLE_FS procedure is similar to mount commands that are used for other local file systems.

  • For better security, Oracle recommends that you use access control lists (ACLs) and Kerberos to control access to sensitive data.

  • Do not attempt to unmount the file system from the operating system level. Doing so can leave the Oracle Database-created file system internal tables in an inconsistent state.

Example

BEGIN
 DBMS_FS.UNMOUNT_ORACLE_FS (
  fsname           => 'dbfs_fs1',                              
  mount_point      => '/oracle/dbfs/testfs',
  mount_options    => 'force'); 
END;