## 33.3. Using Compression/Encryption

Compression can be enabled for particular tablespaces. System relations are not compressed in any case. It is not currently possible to alter tablespace compression option, i.e. it is not possible to compress existing tablespace or vice versa - decompress compressed tablespace.

So to use compression/encryption you need to create a tablespace with `compression=true` option. You can make this tablespace your default tablespace - in this case all tables within the current session will be implicitly created in this tablespace:

        postgres=# create tablespace zfs location '/var/data/cfs' with (compression=true);
        postgres=# set default_tablespace=zfs;

Encryption right now can be only combined with compression: it is not possible to use encryption without compression. To enable encryption you should set `cfs_encryption` parameter to true and provide cipher use by setting `PG_CIPHER_KEY` environment variable.

To configure CFS, use data compression configuration parameters listed in Section 19.14. By default, CFS is configured with one background worker performing garbage collection. Garbage collector traverses tablespace directory, locating map files in it and checking percent of garbage in this file. When ratio of used and allocated spaces exceeds `cfs_gc_threshold` threshold, this file is defragmented. The file is locked at the period of defragmentation, preventing any access to this part of relation. When defragmentation is completed, garbage collection waits `cfs_gc_delay` milliseconds and continue directory traversal. After the end of traversal, GC waits `cfs_gc_period` milliseconds and starts new GC iteration. If there are more than one GC workers, then they split work based on hash of file inode.

CFS provides several functions to manually control CFS garbage collection and get information on CFS state and activity. For the full list of functions, see Section 9.26.11.

To initiate garbage collection manually, use the `cfs_start_gc(n_workers)` function. This function returns number of workers which are actually started. Please notice that if `cfs_gc_workers` parameter is non zero, then GC is performed in background and `cfs_start_gc` function does nothing and returns 0.

It is possible to estimate effect of table compression using `cfs_estimate(relation)` function. This function takes first ten blocks of relation, tries to compress them, and returns average compress ratio. So if returned value is 7.8 then compressed table occupies about eight time less space than original table.

Function `cfs_compression_ratio(relation)` allows to check how precise was estimation of `cfs_estimate(relation)` function. It returns real compression ration for all segments of the compressed relation. Compression ration is total sum of virtual size of all relation segments (number of blocks multiplied by 8kb) divided by sum of physical size of the segment files.

As it was mentioned before, CFS always appends updated blocks to the end of the compressed file. So physical size of the file can be greater than used size in this file. I.e. CFS file is fragmented and defragmentation is periodically performed by CFS garbage collector. `cfs_fragmentation(relation)` functions returns average fragmentation of relation files. It is calculated as sum of physical sizes of the files minus sum of used size of the files divided by sum of physical sizes of the files.

Particular relation can be defragmented using `cfs_gc_relation(relation)` function. This function can be used only if there are no active GC workers (`cfs_gc_workers` equals to zero). It returns number of defragmented segments of relation. If there is on relation with such OID or it is not compressed or some other GC process is active, 0 is returned.

There are several functions allowing to monitors garbage collection activity: `cfs_gc_activity_scanned_files` returns number of files scanned by GC, `cfs_gc_activity_processed_files` returns number of file compacted by GC, `cfs_gc_activity_processed_pages` returns number of pages transferred by GC during files defragmentation, `cfs_gc_activity_processed_bytes` returns total size of transferred pages. All this functions calculate their values since system start.