upscaledb  2.2.0
Macros | Functions
upscaledb Environment Functions

Macros

#define UPS_FLUSH_COMMITTED_TRANSACTIONS   1
 
#define UPS_DONT_LOCK   0xf0000000
 

Functions

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_create (ups_env_t **env, const char *filename, uint32_t flags, uint32_t mode, const ups_parameter_t *param)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_open (ups_env_t **env, const char *filename, uint32_t flags, const ups_parameter_t *param)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_get_parameters (ups_env_t *env, ups_parameter_t *param)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_create_db (ups_env_t *env, ups_db_t **db, uint16_t name, uint32_t flags, const ups_parameter_t *params)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_open_db (ups_env_t *env, ups_db_t **db, uint16_t name, uint32_t flags, const ups_parameter_t *params)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_rename_db (ups_env_t *env, uint16_t oldname, uint16_t newname, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_erase_db (ups_env_t *env, uint16_t name, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_flush (ups_env_t *env, uint32_t flags)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_get_database_names (ups_env_t *env, uint16_t *names, uint32_t *count)
 
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_close (ups_env_t *env, uint32_t flags)
 

Detailed Description

Macro Definition Documentation

#define UPS_DONT_LOCK   0xf0000000

Definition at line 1070 of file upscaledb.h.

#define UPS_FLUSH_COMMITTED_TRANSACTIONS   1

Definition at line 1049 of file upscaledb.h.

Function Documentation

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_close ( ups_env_t env,
uint32_t  flags 
)

Closes the Database Environment

This function closes the Database Environment. It also frees the memory resources allocated in the env handle, and tries to truncate the file (see below).

If the flag UPS_AUTO_CLEANUP is specified, upscaledb automatically calls ups_db_close with flag UPS_AUTO_CLEANUP on all open Databases (which closes all open Databases and their Cursors). This invalidates the ups_db_t and ups_cursor_t handles!

If the flag is not specified, the application must close all Database handles with ups_db_close to prevent memory leaks.

This function also aborts all Transactions which were not yet committed, and therefore renders all Transaction handles invalid. If the flag UPS_TXN_AUTO_COMMIT is specified, all Transactions will be committed.

This function also tries to truncate the file and "cut off" unused space at the end of the file to reduce the file size. This feature is disabled on Win32 if memory mapped I/O is used (see UPS_DISABLE_MMAP).

Parameters
envA valid Environment handle
flagsOptional flags for closing the handle. Possible flags are:
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if env is NULL

Referenced by upscaledb::env::close(), and main().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_create ( ups_env_t **  env,
const char *  filename,
uint32_t  flags,
uint32_t  mode,
const ups_parameter_t param 
)

Creates a Database Environment

A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory). The maximum number of Databases depends on the page size; the default is above 600.

Each Database in an Environment is identified by a positive 16bit value (except 0 and values at or above 0xf000). Databases in an Environment can be created with ups_env_create_db or opened with ups_env_open_db.

Specify a URL instead of a filename (i.e. "ups://localhost:8080/customers.db") to access a remote upscaledb Server.

To enable ACID Transactions, supply the flag UPS_ENABLE_TRANSACTIONS. By default, upscaledb will use a Journal for recovering the Environment and its data in case of a crash, and also to re-apply committed Transactions which were not yet flushed to disk. This Journalling can be disabled with the flag UPS_DISABLE_RECOVERY. (It is disabled if the Environment is in-memory.)

For performance reasons the Journal does not use fsync(2) (or FlushFileBuffers on Win32) to flush modified buffers to disk. Use the flag UPS_ENABLE_FSYNC to force the use of fsync.

If Transactions are enabled, a journal file is written in order to provide recovery if the system crashes. These journal files can be compressed by supplying the parameter UPS_PARAM_ENABLE_JOURNAL_COMPRESSION. Values are one of UPS_COMPRESSOR_ZLIB, UPS_COMPRESSOR_SNAPPY etc. See the upscaledb documentation for more details. This parameter is not persisted.

Upscaledb can transparently encrypt the generated file using 128bit AES in CBC mode. The transactional journal is not encrypted. Encryption can be enabled by specifying UPS_PARAM_ENCRYPTION_KEY (see below). The identical key has to be provided in ups_env_open as well. Ignored for remote Environments.

CRC32 checksums are stored when a page is flushed, and verified when it is fetched from disk if the flag UPS_ENABLE_CRC32 is set. API functions will return UPS_INTEGRITY_VIOLATED in case of failed verifications. Not allowed in In-Memory Environments. This flag is not persisted.

Parameters
envA pointer to an Environment handle
filenameThe filename of the Environment file. If the file already exists, it is overwritten. Can be NULL for an In-Memory Environment. Can be a URL ("ups://<hostname>:<port>/<environment>") for remote access.
flagsOptional flags for opening the Environment, combined with bitwise OR. Possible flags are:
  • UPS_ENABLE_FSYNC Flushes all file handles after committing or aborting a Transaction using fsync(), fdatasync() or FlushFileBuffers(). This file has no effect if Transactions are disabled. Slows down performance but makes sure that all file handles and operating system caches are transferred to disk, thus providing a stronger durability.
  • UPS_IN_MEMORY Creates an In-Memory Environment. No file will be created, and the Database contents are lost after the Environment is closed. The filename parameter can be NULL. Do NOT specify cache_size other than 0.
  • UPS_DISABLE_MMAP Do not use memory mapped files for I/O. By default, upscaledb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used.
  • UPS_CACHE_UNLIMITED Do not limit the cache. Nearly as fast as an In-Memory Database. Not allowed in combination with a limited cache size.
  • UPS_ENABLE_TRANSACTIONS Enables Transactions for this Environment.
  • UPS_DISABLE_RECOVERY Disables logging/recovery for this Environment.
  • UPS_ENABLE_CRC32 Stores (and verifies) CRC32 checksums. Not allowed in combination with UPS_IN_MEMORY.
modeFile access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows. Default is 0644.
paramAn array of ups_parameter_t structures. The following parameters are available:
  • UPS_PARAM_CACHE_SIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as UPS_DEFAULT_CACHE_SIZE - usually 2MB
  • UPS_PARAM_POSIX_FADVISE Sets the "advice" for posix_fadvise(). Only on supported platforms. Allowed values are UPS_POSIX_FADVICE_NORMAL (which is the default) or UPS_POSIX_FADVICE_RANDOM.
  • UPS_PARAM_PAGE_SIZE The size of a file page, in bytes. It is recommended not to change the default size. The default size depends on hardware and operating system. Page sizes must be 1024 or a multiple of 2048.
  • UPS_PARAM_FILE_SIZE_LIMIT Sets a file size limit (in bytes). Disabled by default. Not allowed in combination with UPS_IN_MEMORY. If the limit is exceeded, API functions return UPS_LIMITS_REACHED.
  • UPS_PARAM_LOG_DIRECTORY The path of the log file and the journal files; default is the same path as the database file. Ignored for remote Environments.
  • UPS_PARAM_NETWORK_TIMEOUT_SEC Timeout (in seconds) when waiting for data from a remote server. By default, no timeout is set.
  • UPS_PARAM_ENABLE_JOURNAL_COMPRESSION Compresses the journal files to reduce I/O. See notes above.
  • UPS_PARAM_ENCRYPTION_KEY The 16 byte long AES encryption key; enables AES encryption for the Environment file. Not allowed for In-Memory Environments. Ignored for remote Environments.
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags or parameters was specified
UPS_IO_ERROR if the file could not be opened or reading/writing failed
UPS_INV_FILE_VERSION if the Environment version is not compatible with the library version
UPS_OUT_OF_MEMORY if memory could not be allocated
UPS_INV_PAGE_SIZE if page_size is not 1024 or a multiple of 2048
UPS_INV_KEY_SIZE if key_size is too large (at least 4 keys must fit in a page)
UPS_WOULD_BLOCK if another process has locked the file
UPS_ENVIRONMENT_ALREADY_OPEN if env is already in use
See also
ups_env_create
ups_env_close
ups_env_open

Referenced by upscaledb::env::create(), and main().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_create_db ( ups_env_t env,
ups_db_t **  db,
uint16_t  name,
uint32_t  flags,
const ups_parameter_t params 
)

Creates a new Database in a Database Environment

An Environment can contain a (limited) amount of Databases; the exact limit depends on the page size and is above 600.

Each Database in an Environment is identified by a positive 16bit value. 0 and values at or above 0xf000 are reserved.

This function initializes the ups_db_t handle (the second parameter). When the handle is no longer in use, it should be closed with ups_db_close. Alternatively, the Database handle is closed automatically if ups_env_close is called with the flag UPS_AUTO_CLEANUP.

A Database can (and should) be configured and optimized for the data that is inserted. The data is described through flags and parameters. upscaledb differentiates between several data characteristics, and offers predefined "types" to describe the keys. In general, the default key type (UPS_TYPE_BINARY) is slower than the other types, and fixed-length binary keys (UPS_TYPE_BINARY in combination with UPS_PARAM_KEY_SIZE) is faster than variable-length binary keys. It is therefore recommended to always set the key size and record size, although it is not required.

Internally, upscaledb uses two different layouts ("default" and "pax) depending on the settings specified by the user. The "default" layout is enabled for variable-length keys or if duplicate keys are enabled. For fixed-length keys (without duplicates) the "pax" layout is chosen. The "pax" layout is more compact and usually faster.

A word of warning regarding the use of fixed length binary keys (UPS_TYPE_CUSTOM or UPS_TYPE_BINARY in combination with UPS_PARAM_KEY_SIZE): if your key size is too large, only few keys will fit in a Btree node. The Btree fanout will be very high, which will decrease performance. In such cases it might be better to NOT specify the key size; then upscaledb will store keys as blobs if they are too large.

See the Wiki documentation for Evaluating and Benchmarking on how to test different configurations and optimize for performance.

The key type is set with UPS_PARAM_KEY_TYPE and the record type is set with UPS_PARAM_RECORD_TYPE. The types can have one of the following values:

  • UPS_TYPE_BINARY This is the default typef or keys and records: a binary blob with fixed or variable length. Internally, upscaledb uses memcmp(3) for the sort order of binary keys. Key size depends on UPS_PARAM_KEY_SIZE and is unlimited (UPS_KEY_SIZE_UNLIMITED) by default. Record size depends on UPS_PARAM_RECORD_SIZE and is unlimited (UPS_RECORD_SIZE_UNLIMITED) by default.
  • UPS_TYPE_CUSTOM Only for keys: similar to UPS_TYPE_BINARY, but uses a callback function for the sort order. This function is set with the parameter UPS_PARAM_CUSTOM_COMPARE_NAME.
  • UPS_TYPE_UINT8 Key is a 8bit (1 byte) unsigned integer
  • UPS_TYPE_UINT16 Key is a 16bit (2 byte) unsigned integer
  • UPS_TYPE_UINT32 Key is a 32bit (4 byte) unsigned integer
  • UPS_TYPE_UINT64 Key is a 64bit (8 byte) unsigned integer
  • UPS_TYPE_REAL32 Key is a 32bit (4 byte) float
  • UPS_TYPE_REAL64 Key is a 64bit (8 byte) double

If the type is ommitted then UPS_TYPE_BINARY is the default.

If binary/custom keys are so big that they cannot be stored in the Btree, then the full key will be stored in an overflow area, which has performance implications when accessing such keys.

In addition to the flags above, you can specify UPS_ENABLE_DUPLICATE_KEYS to insert duplicate keys, i.e. to model 1:n or n:m relationships.

If the size of the records is always constant, then UPS_PARAM_RECORD_SIZE should be used to specify this size. This allows upscaledb to optimize the record storage, and small records will automatically be stored in the Btree's leaf nodes instead of a separately allocated blob, allowing faster access. Setting a record size to 0 is valid and suited for boolean values ("key exists" vs "key doesn't exist"). The default record size is UPS_RECORD_SIZE_UNLIMITED.

Records can be compressed transparently in order to reduce I/O and disk space. Compression is enabled with UPS_PARAM_RECORD_COMPRESSION. Values are one of UPS_COMPRESSOR_ZLIB, UPS_COMPRESSOR_SNAPPY etc. See the upscaledb documentation for more details.

Keys can also be compressed by setting the parameter UPS_PARAM_KEY_COMPRESSION. See the upscaledb documentation for more details.

In addition, experimental integer compression algorithms are available for Databases created with the type UPS_TYPE_UINT32. These algorithms (UPS_COMPRESSOR_UINT32_VARBYTE, UPS_COMPRESSOR_UINT32_SIMDCOMP, UPS_COMPRESSOR_UINT32_GROUPVARINT, UPS_COMPRESSOR_UINT32_STREAMVBYTE, UPS_COMPRESSOR_UINT32_FOR, UPS_COMPRESSOR_UINT32_MASKEDVBYTE (requires AVX!)) are subject to change and might be removed in following versions. They only work with the default page size of 16kb.

Parameters
envA valid Environment handle.
dbA valid Database handle, which will point to the created Database. To close the handle, use ups_db_close.
nameThe name of the Database. If a Database with this name already exists, the function will fail with UPS_DATABASE_ALREADY_EXISTS. Database names from 0xf000 to 0xffff and 0 are reserved.
flagsOptional flags for creating the Database, combined with bitwise OR. Possible flags are:
  • UPS_ENABLE_DUPLICATE_KEYS Enable duplicate keys for this Database. By default, duplicate keys are disabled.
  • UPS_RECORD_NUMBER32 Creates an "auto-increment" Database. Keys in Record Number Databases are automatically assigned an incrementing 32bit value. If key->data is not NULL (and key->flags is UPS_KEY_USER_ALLOC), the value of the current key is returned in key. If key-data is NULL and key->size is 0, key->data is temporarily allocated by upscaledb.
  • UPS_RECORD_NUMBER64 Creates an "auto-increment" Database. Keys in Record Number Databases are automatically assigned an incrementing 64bit value. If key->data is not NULL (and key->flags is UPS_KEY_USER_ALLOC), the value of the current key is returned in key. If key-data is NULL and key->size is 0, key->data is temporarily allocated by upscaledb.
paramsAn array of ups_parameter_t structures. The following parameters are available:
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags was specified
UPS_DATABASE_ALREADY_EXISTS if a Database with this name already exists in this Environment
UPS_OUT_OF_MEMORY if memory could not be allocated
UPS_LIMITS_REACHED if the maximum number of Databases per Environment was already created

Referenced by upscaledb::env::create_db(), and main().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_erase_db ( ups_env_t env,
uint16_t  name,
uint32_t  flags 
)

Deletes a Database from an Environment

Parameters
envA valid Environment handle
nameThe name of the Database to delete. If a Database with this name does not exist, the function will fail with UPS_DATABASE_NOT_FOUND. If the Database was already opened, the function will fail with UPS_DATABASE_ALREADY_OPEN.
flagsOptional flags for deleting the Database; unused, set to 0.
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if the env pointer is NULL or if the new Database name is reserved
UPS_DATABASE_NOT_FOUND if a Database with this name does not exist
UPS_DATABASE_ALREADY_OPEN if a Database with this name is still open

Referenced by upscaledb::env::erase_db().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_flush ( ups_env_t env,
uint32_t  flags 
)

Flushes the Environment

This function flushes the Environment caches and writes the whole file to disk. All Databases of this Environment are flushed as well.

Since In-Memory Databases do not have a file on disk, the function will have no effect and will return UPS_SUCCESS.

Parameters
envA valid Environment handle
flagsOptional flags for flushing; unused, set to 0
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if db is NULL

Referenced by upscaledb::env::flush().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_get_database_names ( ups_env_t env,
uint16_t names,
uint32_t count 
)

Returns the names of all Databases in an Environment

This function returns the names of all Databases and the number of Databases in an Environment.

The memory for names must be allocated by the user. count must be the size of names when calling the function, and will be the number of Databases when the function returns. The function returns UPS_LIMITS_REACHED if names is not big enough; in this case, the caller should resize the array and call the function again.

Parameters
envA valid Environment handle
namesPointer to an array for the Database names
countPointer to the size of the array; will be used to store the number of Databases when the function returns.
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if env, names or count is NULL
UPS_LIMITS_REACHED if names is not large enough to hold all Database names

Referenced by upscaledb::env::get_database_names().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_get_parameters ( ups_env_t env,
ups_parameter_t param 
)

Retrieve the current value for a given Environment setting

Only those values requested by the parameter array will be stored.

The following parameters are supported:

  • UPS_PARAM_CACHE_SIZE returns the cache size
  • UPS_PARAM_PAGE_SIZE returns the page size
  • UPS_PARAM_MAX_DATABASES returns the max. number of Databases of this Database's Environment
  • UPS_PARAM_FLAGS returns the flags which were used to open or create this Database
  • UPS_PARAM_FILEMODE returns the mode parameter which was specified when creating this Database
  • UPS_PARAM_FILENAME returns the filename (the value of this parameter is a const char * pointer casted to a uint64_t variable)
  • UPS_PARAM_LOG_DIRECTORY The path of the log file and the journal files. Ignored for remote Environments.
  • UPS_PARAM_JOURNAL_COMPRESSION Returns the selected algorithm for journal compression, or 0 if compression is disabled
Parameters
envA valid Environment handle
paramAn array of ups_parameter_t structures
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if the env pointer is NULL or param is NULL

Referenced by upscaledb::env::get_parameters().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_open ( ups_env_t **  env,
const char *  filename,
uint32_t  flags,
const ups_parameter_t param 
)

Opens an existing Database Environment

This function opens an existing Database Environment.

A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory).

Each Database in an Environment is identified by a positive 16bit value (except 0 and values at or above 0xf000). Databases in an Environment can be created with ups_env_create_db or opened with ups_env_open_db.

Specify a URL instead of a filename (i.e. "ups://localhost:8080/customers.db") to access a remote upscaledb Server.

Also see the documentation ups_env_create about Transactions, Recovery, AES encryption and the use of fsync.

If Transactions are enabled, a journal file is written in order to provide recovery if the system crashes. These journal files can be compressed by supplying the parameter UPS_PARAM_JOURNAL_COMPRESSION. Values are one of UPS_COMPRESSOR_ZLIB, UPS_COMPRESSOR_SNAPPY etc. See the upscaledb documentation for more details. This parameter is not persisted.

CRC32 checksums are stored when a page is flushed, and verified when it is fetched from disk if the flag UPS_ENABLE_CRC32 is set. API functions will return UPS_INTEGRITY_VIOLATED in case of failed verifications. This flag is not persisted.

Parameters
envA valid Environment handle
filenameThe filename of the Environment file, or URL of a upscaledb Server
flagsOptional flags for opening the Environment, combined with bitwise OR. Possible flags are:
  • UPS_READ_ONLY Opens the file for reading only. Operations that need write access (i.e. ups_db_insert) will return UPS_WRITE_PROTECTED.
  • UPS_ENABLE_FSYNC Flushes all file handles after committing or aborting a Transaction using fsync(), fdatasync() or FlushFileBuffers(). This file has no effect if Transactions are disabled. Slows down performance but makes sure that all file handles and operating system caches are transferred to disk, thus providing a stronger durability.
  • UPS_DISABLE_MMAP Do not use memory mapped files for I/O. By default, upscaledb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used.
  • UPS_CACHE_UNLIMITED Do not limit the cache. Nearly as fast as an In-Memory Database. Not allowed in combination with a limited cache size.
  • UPS_ENABLE_TRANSACTIONS Enables Transactions for this Environment.
  • UPS_DISABLE_RECOVERY Disables logging/recovery for this Environment.
  • UPS_AUTO_RECOVERY Automatically recover the Environment, if necessary.
  • UPS_ENABLE_CRC32 Stores (and verifies) CRC32 checksums.
paramAn array of ups_parameter_t structures. The following parameters are available:
Returns
UPS_SUCCESS upon success.
UPS_INV_PARAMETER if the env pointer is NULL, an invalid combination of flags was specified
UPS_FILE_NOT_FOUND if the file does not exist
UPS_IO_ERROR if the file could not be opened or reading failed
UPS_INV_FILE_VERSION if the Environment version is not compatible with the library version.
UPS_OUT_OF_MEMORY if memory could not be allocated
UPS_WOULD_BLOCK if another process has locked the file
UPS_NEED_RECOVERY if the Database is in an inconsistent state
UPS_LOG_INV_FILE_HEADER if the logfile is corrupt
UPS_ENVIRONMENT_ALREADY_OPEN if env is already in use
UPS_NETWORK_ERROR if a remote server is not reachable

Referenced by main(), and upscaledb::env::open().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_open_db ( ups_env_t env,
ups_db_t **  db,
uint16_t  name,
uint32_t  flags,
const ups_parameter_t params 
)

Opens a Database in a Database Environment

Each Database in an Environment is identified by a positive 16bit value (except 0 and values at or above 0xf000).

This function initializes the ups_db_t handle (the second parameter). When the handle is no longer in use, it should be closed with ups_db_close. Alternatively, the Database handle is closed automatically if ups_env_close is called with the flag UPS_AUTO_CLEANUP.

If this database stores keys with a custom compare function then you have to install the compare function (ups_register_compare) prior to opening the database.

Records can be compressed transparently in order to reduce I/O and disk space. Compression is enabled with UPS_PARAM_ENABLE_RECORD_COMPRESSION. Values are one of UPS_COMPRESSOR_ZLIB, UPS_COMPRESSOR_SNAPPY etc. See the upscaledb documentation for more details. This parameter is not persisted.

Parameters
envA valid Environment handle
dbA valid Database handle, which will point to the opened Database. To close the handle, use
See also
ups_db_close.
Parameters
nameThe name of the Database. If a Database with this name does not exist, the function will fail with UPS_DATABASE_NOT_FOUND.
flagsOptional flags for opening the Database, combined with bitwise OR. Possible flags are:
paramsReserved; set to NULL
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags was specified
UPS_DATABASE_NOT_FOUND if a Database with this name does not exist in this Environment.
UPS_DATABASE_ALREADY_OPEN if this Database was already opened
UPS_OUT_OF_MEMORY if memory could not be allocated
UPS_NOT_READY if the database requires a custom callback function, but this function was not yet registered

Referenced by main(), and upscaledb::env::open_db().

UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_rename_db ( ups_env_t env,
uint16_t  oldname,
uint16_t  newname,
uint32_t  flags 
)

Renames a Database in an Environment.

Parameters
envA valid Environment handle.
oldnameThe old name of the existing Database. If a Database with this name does not exist, the function will fail with UPS_DATABASE_NOT_FOUND.
newnameThe new name of this Database. If a Database with this name already exists, the function will fail with UPS_DATABASE_ALREADY_EXISTS.
flagsOptional flags for renaming the Database, combined with bitwise OR; unused, set to 0.
Returns
UPS_SUCCESS upon success
UPS_INV_PARAMETER if the env pointer is NULL or if the new Database name is reserved
UPS_DATABASE_NOT_FOUND if a Database with this name does not exist in this Environment
UPS_DATABASE_ALREADY_EXISTS if a Database with the new name already exists
UPS_OUT_OF_MEMORY if memory could not be allocated
UPS_NOT_READY if the Environment env was not initialized correctly (i.e. not yet opened or created)

Referenced by upscaledb::env::rename_db().