Oracle Berkeley DB

https://docs.oracle.com/database/bdb181/
Admin
Oracle Berkeley DB is an embedded key-value database library that provides scalable,...
Tokens:7,863,506
Snippets:15,955
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Getting Started with Replication Guides

Source: https://docs.oracle.com/database/bdb181/books

Guides for setting up and managing replication in Berkeley DB environments, available for C, C++, and Java. PDF versions are included.

```C
Getting Started with Replication (C):
  Access: ./html/gsg_db_rep/C/index.html
  PDF: ./html/gsg_db_rep/C/Replication-C-GSG.pdf
  Description: Guide for C developers on Berkeley DB replication.
```

```C++
Getting Started with Replication (C++):
  Access: ./html/gsg_db_rep/CXX/index.html
  PDF: ./html/gsg_db_rep/CXX/Replication-CXX-GSG.pdf
  Description: Guide for C++ developers on Berkeley DB replication.
```

```Java
Getting Started with Replication (Java):
  Access: ./html/gsg_db_rep/JAVA/index.html
  PDF: ./html/gsg_db_rep/JAVA/Replication-JAVA-GSG.pdf
  Description: Guide for Java developers on Berkeley DB replication.
```

--------------------------------

### Getting Started with Data Storage Guides

Source: https://docs.oracle.com/database/bdb181/books

Guides for getting started with data storage in Berkeley DB, available for C, C++, and Java. Each guide includes a PDF version.

```C
Getting Started with Data Storage (C):
  Access: ./html/gsg/C/index.html
  PDF: ./html/gsg/C/BerkeleyDB-Core-C-GSG.pdf
  Description: Guide for C developers on data storage with Berkeley DB.
```

```C++
Getting Started with Data Storage (C++):
  Access: ./html/gsg/CXX/index.html
  PDF: ./html/gsg/CXX/BerkeleyDB-Core-Cxx-GSG.pdf
  Description: Guide for C++ developers on data storage with Berkeley DB.
```

```Java
Getting Started with Data Storage (Java):
  Access: ./html/gsg/JAVA/index.html
  PDF: ./html/gsg/JAVA/BerkeleyDB-Core-JAVA-GSG.pdf
  Description: Guide for Java developers on data storage with Berkeley DB.
```

--------------------------------

### ex_rep_mgr Master and Client Examples

Source: https://docs.oracle.com/database/bdb181/html/programmer_reference/rep_ex

Provides example command-line invocations for starting a master and multiple clients using the ex_rep_mgr application. Demonstrates how to set priorities and connection details for replication setup.

```shell
# Start a master
ex_rep_mgr -M -p 100 -h DIR1 -l localhost:30100

# Start several clients
ex_rep_mgr -C  -p 50 -h DIR2 -l localhost:30101 -r localhost:30100
ex_rep_mgr -C -p 10 -h DIR3 -l localhost:30102 -r localhost:30100
ex_rep_mgr -C -p 0 -h DIR4 -l localhost:30103 -r localhost:30100
```

--------------------------------

### Start ex_rep_chan Client Instances

Source: https://docs.oracle.com/database/bdb181/html/programmer_reference/rep_ex_chan

Example commands to start client instances of the ex_rep_chan application, connecting to a master via a helper site.

```shell
ex_rep_chan -C -h DIR2 -l localhost:30101 -r localhost:30100
ex_rep_chan -C -h DIR3 -l localhost:30102 -r localhost:30100
ex_rep_chan -C -h DIR4 -l localhost:30103 -r localhost:30100
```

--------------------------------

### Start ex_rep_chan Master Instance

Source: https://docs.oracle.com/database/bdb181/html/programmer_reference/rep_ex_chan

Example command to start a master instance of the ex_rep_chan application, specifying its home directory and listening port.

```shell
ex_rep_chan -M -h DIR1 -l localhost:30100
```

--------------------------------

### Test Go Berkeley DB (go-bdb) Example

Source: https://docs.oracle.com/database/bdb181/html/installation/build_thirdparty

Demonstrates how to run a basic 'Hello World' example for the Go Berkeley DB bindings to verify a successful installation. It involves navigating to the example directory and executing the Go program.

```go
go run HelloWorld.go
```

--------------------------------

### Initialize and Start Master Process

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/C/exampledoloop

Steps to initialize the environment home directory and start the first replication manager process as the master.

```shell
> mkdir env1
> ./ex_rep_gsg_repmgr -h env1 -L localhost:8080 -p 10
No stock database yet available.
No stock database yet available.
```

--------------------------------

### Start Replica Process and Connect

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/C/exampledoloop

Steps to initialize a second environment home directory and start a second replication manager process as a replica, connecting it to the master.

```shell
> mkdir env2
> ./ex_rep_gsg_repmgr -h env2 -l localhost:8081 \
-r localhost:8080 -p 20
```

--------------------------------

### Main Application Execution Flow

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/C/repmgr_init_example_c

Orchestrates the database environment setup, replication start, and main application loop. Includes error handling and closing the environment.

```c
/* Error check command line. */
if (home == NULL || !local_is_set)
    usage();

if ((ret = env_init(dbenv, home)) != 0)
    goto err;

if ((ret = dbenv->repmgr_start(dbenv, 3, DB_REP_ELECTION)) != 0)
    goto err;

if ((ret = doloop(dbenv)) != 0) {
    dbenv->err(dbenv, ret, "Application failed");
    goto err;
}

err: if (dbenv != NULL)
        (void)dbenv->close(dbenv, 0);

    return (ret);
}
```

--------------------------------

### Example 2: Site 2 Replica Startup

Source: https://docs.oracle.com/database/bdb181/html/bdb-sql/rep_usageexamples

Starts a replica site, connecting it to the master site. This replica will receive updates from the master.

```shell
# Start replica.
# quote.db does not yet exist.
dbsql quote.db
     pragma replication_local_site="site2:7001";
     pragma replication_remote_site="site1:7000";
     pragma replication=ON;
```

--------------------------------

### Create and Open Database Instance (Java)

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/JAVA/preface

Shows an updated Java code snippet that includes creating a Database object using a previously configured DatabaseConfig. This example illustrates opening a database file named 'mydb.db'.

```java
import com.sleepycat.db.Database;
import com.sleepycat.db.DatabaseConfig;

...

// Allow the database to be created.
DatabaseConfig myDbConfig = new DatabaseConfig();
myDbConfig.setAllowCreate(true);
Database myDb = new Database("mydb.db", null, myDbConfig);
```

--------------------------------

### Example 1: Site 2 Replica Startup

Source: https://docs.oracle.com/database/bdb181/html/bdb-sql/rep_usageexamples

Starts the first replica site, connecting it to the initial master. This allows read operations to be distributed to this site.

```shell
# Start first replica.
# univ.db does not yet exist.
dbsql univ.db
     pragma replication_local_site="site2:7001";
     pragma replication_remote_site="site1:7000";
     pragma replication=ON;
```

--------------------------------

### Example 1: Site 3 Replica Startup

Source: https://docs.oracle.com/database/bdb181/html/bdb-sql/rep_usageexamples

Starts the second replica site, also connecting it to the initial master. This further distributes read load and increases redundancy.

```shell
# Start second replica.
# univ.db does not yet exist.
dbsql univ.db
     pragma replication_local_site="site3:7002";
     pragma replication_remote_site="site1:7000";
     pragma replication=ON;
```

--------------------------------

### Start Replication Manager

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/JAVA/repmgr_init_example_c

Starts the Replication Manager after the environment has been configured and opened. It uses a specified startup policy and timeout.

```Java
// start Replication Manager
        dbenv.replicationManagerStart(3, appConfig.startPolicy);
        return ret;
    }
```

--------------------------------

### Example 2: Site 1 Master Startup

Source: https://docs.oracle.com/database/bdb181/html/bdb-sql/rep_usageexamples

Starts the initial master site for replication using the quote application database. It creates the stock_quote table.

```shell
# Start initial master.
# quote.db does not yet exist.
dbsql quote.db
     pragma replication_local_site="site1:7000";
     pragma replication_initial_master=ON;
     pragma replication=ON;

    # Create stock quote application table.
    create table stock_quote (company_name text(40), price real);
```

--------------------------------

### RepQuoteExampleGSG Main Method and Argument Parsing

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/JAVA/repmgr_init_example_c

The main method initializes the application, parses command-line arguments to configure replication settings, and sets up the environment.

```Java
    public static void main(String[] argv)
        throws Exception
    {
        RepConfig config = new RepConfig();
        boolean isCreator = false;
        int tmpPort = 0;

        // Extract the command line parameters
        for (int i = 0; i < argv.length; i++)
        {
            if (argv[i].compareTo("-h") == 0) {
                // home is a string arg.
                i++;
                config.home = argv[i];
            } else if (argv[i].compareTo("-l") == 0) ||
              argv[i].compareTo("-L") == 0) {
                if (i == argv.length - 1)
                    usage();
                if (argv[i].compareTo("-L") == 0)
                    isCreator = true;
                // "local" should be host:port.
                i++;
                String[] words = argv[i].split(":");
                if (words.length != 2) {
                   System.err.println(
                     "Invalid host specification host:port needed.");
                    usage();
                }
                try {
                    tmpPort = Integer.parseInt(words[1]);
                } catch (NumberFormatException nfe) {
                    System.err.println("Invalid host specification, " +
                        "could not parse port number.");
                    usage();
                }
                config.setThisHost(words[0], tmpPort, isCreator);
            } else if (argv[i].compareTo("-p") == 0) {
                i++;
                config.priority = Integer.parseInt(argv[i]);
            } else if (argv[i].compareTo("-r") == 0) {
                i++;
                String[] words = argv[i].split(":");
                if (words.length != 2) {
                   System.err.println(
                     "Invalid host specification host:port needed.");
                   usage();
                }
                try {
                    // Code for parsing remote host/port would follow here
                } catch (NumberFormatException nfe) {
                    System.err.println("Invalid host specification, " +
                        "could not parse port number.");
                    usage();
                }
            }
        }
        // Further logic for setting up replication would follow
    }
}
```

--------------------------------

### STOCK_DBS Structure Definition

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/C/preface

Defines the structure used to hold database handles and directory information for inventory and vendor databases. This structure is part of the common header file for getting started examples.

```c
/* File: gettingstarted_common.h */
typedef struct stock_dbs {
    DB *inventory_dbp; /* Database containing inventory information */
    DB *vendor_dbp;    /* Database containing vendor information */

    char *db_home_dir;       /* Directory containing the database
                              * files */
    char *inventory_db_name; /* Name of the inventory database */
    char *vendor_db_name;    /* Name of the vendor database */
} STOCK_DBS;

```

--------------------------------

### Java MyDbs setup() Method

Source: https://docs.oracle.com/database/bdb181/html/gsg/JAVA/CoreJavaUsage

The setup() method configures database parameters such as error stream, prefix, type (BTREE), and allows creation. It then opens or creates and opens the vendor and inventory databases, including error handling for FileNotFoundException.

```java
// The setup() method opens all our databases
// for us.
public void setup(String databasesHome)
    throws DatabaseException {

    DatabaseConfig myDbConfig = new DatabaseConfig();

    myDbConfig.setErrorStream(System.err);
    myDbConfig.setErrorPrefix("MyDbs");
    myDbConfig.setType(DatabaseType.BTREE);
    myDbConfig.setAllowCreate(true);

    // Now open, or create and open, our databases
    // Open the vendors and inventory databases
    try {
        vendordb = databasesHome + "/" + vendordb;
        vendorDb = new Database(vendordb,
                                null,
                                myDbConfig);

        inventorydb = databasesHome + "/" + inventorydb;
        inventoryDb = new Database(inventorydb,
                                    null,
                                    myDbConfig);
    } catch(FileNotFoundException fnfe) {
        System.err.println("MyDbs: " + fnfe.toString());
        System.exit(-1);
    }
}
```

--------------------------------

### C main() Environment Configuration and Replication Setup

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/C/exampledoloop

Configures the Berkeley DB environment handle, setting application data, replication priority, acknowledgment policy, and timeouts. It also parses command-line arguments to set up replication sites, host/port specifications, and group creator status, and initializes the environment.

```c
    if ((ret = create_env(progname, &dbenv)) != 0)
            goto err;

    /* Make APP_DATA available through the environment handle */
    dbenv->app_private = &my_app_data;

    /* Default priority is 100 */
    dbenv->rep_set_priority(dbenv, 100);
    /* Permanent messages require at least one ack */
    dbenv->repmgr_set_ack_policy(dbenv, DB_REPMGR_ACKS_ONE);
    /* Give 500 microseconds to receive the ack */
    dbenv->rep_set_timeout(dbenv, DB_REP_ACK_TIMEOUT, 500);

    while ((ch = getopt(argc, argv, "h:l:L:p:r:")) != EOF)
        switch (ch) {
        case 'h':
            home = optarg;
            break;
        /* Set the host and port used by this environment */
        case 'L':
            is_group_creator = 1; /* FALLTHROUGH */
        case 'l':
            host = strtok(optarg, ":");
            if ((portstr = strtok(NULL, ":")) == NULL) {
                fprintf(stderr, "Bad host specification.\n");
                goto err;
            }
            port = (unsigned short)atoi(portstr);
            if ((ret = dbenv->repmgr_site(dbenv, host, port, &dbsite
                                          0)) != 0 ) {
                fprintf(stderr,
                    "Could not set local address %s.\n", host);
                goto err;
            }
            dbsite->set_config(dbsite, DB_LOCAL_SITE, 1);
            if (is_group_creator)
                dbsite->set_config(dbsite, DB_GROUP_CREATOR, 1);

            if ((ret = dbsite->close(dbsite)) != 0) {
                dbenv->err(dbenv, ret, "DB_SITE->close");
                goto err;
            }
            local_is_set = 1;
            break;
        /* Set this replica's election priority */
        case 'p':
            dbenv->rep_set_priority(dbenv, atoi(optarg));
            break;
        /* Identify another site in the replication group */
        case 'r':
            host = strtok(optarg, ":");
            if ((portstr = strtok(NULL, ":")) == NULL) {
                fprintf(stderr, "Bad host specification.\n");
                goto err;
            }
            port = (unsigned short)atoi(portstr);
            if ((dbenv->repmgr_site(dbenv, host, port, &dbsite,
                                      0)) != 0) {
                dbenv->err(dbenv, ret, "DB_ENV->repmgr_site");
                goto err;
            }
            dbenv->set_config(dbsite, DB_BOOTSTRAP_HELPER, 1);
            if ((dbenv->close(dbsite)) != 0) {
                dbenv->err(dbenv, ret, "DB_SITE->close");
                goto err;
            }
            break;
        case '?':
        default:
            usage();
        }

    /* Error check command line. */
    if (home == NULL || !local_is_set)
        usage();

    if ((ret = env_init(dbenv, home)) != 0)
            goto err;
```

--------------------------------

### Getting Started with Transactional Processing Guides

Source: https://docs.oracle.com/database/bdb181/books

Guides for implementing transactional processing in Berkeley DB applications, provided for C, C++, and Java. PDF versions are available.

```C
Getting Started with Transactional Processing (C):
  Access: ./html/gsg_txn/C/index.html
  PDF: ./html/gsg_txn/C/BerkeleyDB-Core-C-Txn.pdf
  Description: Guide for C developers on transactional processing with Berkeley DB.
```

```C++
Getting Started with Transactional Processing (C++):
  Access: ./html/gsg_txn/CXX/index.html
  PDF: ./html/gsg/CXX/BerkeleyDB-Core-Cxx-GSG.pdf
  Description: Guide for C++ developers on transactional processing with Berkeley DB.
```

```Java
Getting Started with Transactional Processing (Java):
  Access: ./html/gsg_txn/JAVA/index.html
  PDF: ./html/gsg_txn/JAVA/BerkeleyDB-Core-JAVA-Txn.pdf
  Description: Guide for Java developers on transactional processing with Berkeley DB.
```

--------------------------------

### Java Deadlock Detection and Transaction Start

Source: https://docs.oracle.com/database/bdb181/html/gsg_txn/JAVA/txnexample_java

Demonstrates the start of a `try` block for deadlock detection and transaction initiation in Java. It outlines the process of obtaining a database transaction using `myEnv.beginTransaction()`.

```java
// while loop is used for deadlock retries
while (retry) {
    // try block used for deadlock detection and
    // general db exception handling
    try {
        // Get a transaction
        txn = myEnv.beginTransaction(null, null);

```

--------------------------------

### Run Method Initialization

Source: https://docs.oracle.com/database/bdb181/html/gsg_txn/JAVA/txnexample_java

The entry point for the DBWriter thread. It initializes a transaction handle and starts a loop to perform 50 transactions, demonstrating transactional behavior and deadlock handling.

```java
    // Thread method that writes a series of records
    // to the database using transaction protection.
    // Deadlock handling is demonstrated here.
    public void run () {

        Transaction txn = null;

        // Perform 50 transactions
        for (int i=0; i<50; i++) {

           boolean retry = true;

```

--------------------------------

### Getting Started with Distributed Berkeley DB Applications (Java)

Source: https://docs.oracle.com/database/bdb181/books

Guides users on developing distributed Berkeley DB applications using Java. A PDF version is available for download.

```APIDOC
Getting Started with Distributed Berkeley DB Applications (Java):
  Access: ./html/gsg_db_server/JAVA/index.html
  PDF: ./html/gsg_db_server/JAVA/Server-JAVA-GSG.pdf
  Description: Tutorial for building distributed Berkeley DB applications in Java.
```

--------------------------------

### Install Berkeley DB with Custom Prefix

Source: https://docs.oracle.com/database/bdb181/html/installation/build_unix_install

Example of specifying the prefix during the make install process to change the entire installation tree location.

```shell
make prefix=/usr/contrib/bdb install
```

--------------------------------

### Configure Berkeley DB Installation

Source: https://docs.oracle.com/database/bdb181/html/installation/build_unix_install

Example of setting the bindir during the configure step to customize installation paths.

```shell
../dist/configure --bindir=/usr/local/bin
```

--------------------------------

### RepQuoteExampleGSG Command Line Usage

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/JAVA/repmgr_init_example_c

Provides the command-line interface usage instructions for the RepQuoteExampleGSG application, detailing required and optional parameters for replication configuration.

```APIDOC
usage: db.repquote_gsg.RepQuoteExampleGSG
-h home -l|-L host:port [-r host:port] [-p priority]

Parameters:
  -h home directory (required)
    Specifies the directory for the database environment.

  -l host:port (required, unless -L is specified; 'l' stands for local)
    Specifies the local host and port for listening to replication messages.

  -L host:port (optional; 'L' means group creator)
    Specifies the local site as the group creator.

  -r host:port (optional; 'r' stands for remote; any number of these may be specified)
    Specifies other replica host and port addresses.

  -p priority (optional: defaults to 100)
    Specifies the replica's election priority, used as a tie-breaker for elections.
```

--------------------------------

### Java Commit Transaction and Count Records

Source: https://docs.oracle.com/database/bdb181/html/gsg_txn/JAVA/txnexample_java

Illustrates committing a transaction and counting records in Java, using uncommitted reads to avoid self-deadlock. It calls `countRecords(null)` to get the current record count before committing.

```java
// commit
System.out.println(getName() + " : committing txn : "
    + i);

// Using uncommitted reads to avoid the deadlock, so
// null is passed for the transaction here.
System.out.println(getName() + " : Found " +
    countRecords(null) + " records in the database.");

```

--------------------------------

### Run BFILE Extension Examples

Source: https://docs.oracle.com/database/bdb181/html/installation/build_unix_sql

Commands to execute the example programs for the BFILE extension after building and installation. It includes setting the library path and running executables for both SQL expressions and C-functions interfaces.

```shell
cd lang/sql/sqlite/ext/bfile/build
export LD_LIBRARY_PATH=$PWD:$DBSQL_DIR/lib
./bfile_example_sql     # for SQL expressions interface
./bfile_example_capi    # for C-functions API
```

--------------------------------

### Parsing Command Line Arguments for Replication

Source: https://docs.oracle.com/database/bdb181/html/gsg_db_rep/C/repmgr_init_example_c

This C snippet illustrates the command-line argument parsing loop using `getopt`. It handles options for environment home directory (-h), listening host/port (-l, -L), and election priority (-p), extracting and processing host and port specifications.

```c
    /* Collect the command line options */
    while ((ch = getopt(argc, argv, "h:l:L:p:r:")) != EOF)
        switch (ch) {
        case 'h':
            home = optarg;
            break;
        /* Set the host and port used by this environment */
        case 'L':
            is_group_creator = 1; /* FALLTHROUGH */
        case 'l':
            host = strtok(optarg, ":");
            if ((portstr = strtok(NULL, ":")) == NULL) {
                fprintf(stderr, "Bad host specification.\n");
                goto err;
            }
            port = (unsigned short)atoi(portstr);

```

--------------------------------

### Enable Key-Store Based User Authentication

Source: https://docs.oracle.com/database/bdb181/html/installation/build_android_jdbc

Key-store based user authentication is enabled by setting `BDB_ENABLE_USERAUTH_KEYSTORE` to `true` in the `Android.mk` file. This functionality also depends on BDB encryption being enabled. Consult the Berkeley DB Getting Started guide for specifics.

```shell
# Edit <db>/build_android/jdbc/jni/Android.mk
# Change BDB_ENABLE_USERAUTH_KEYSTORE from false to true
```

--------------------------------

### Java: TxnGuide Main Method

Source: https://docs.oracle.com/database/bdb181/html/gsg_txn/JAVA/txnexample_java

The main entry point for the application. It orchestrates the parsing of arguments, opening of the environment and databases, creation of a stored class catalog, starting worker threads, and ensuring proper cleanup via `closeEnv()`.

```Java
    public static void main(String args[]) {
        try {
            // Parse the arguments list
            parseArgs(args);
            // Open the environment and databases
            openEnv();
            // Get our class catalog (used to serialize objects)
            StoredClassCatalog classCatalog =
                new StoredClassCatalog(myClassDb);

            // Start the threads
            DBWriter[] threadArray;
            threadArray = new DBWriter[NUMTHREADS];
            for (int i = 0; i < NUMTHREADS; i++) {
                threadArray[i] = new DBWriter(myEnv, myDb, classCatalog);
                threadArray[i].start();
            }

            // Join the threads. That is, wait for each thread to
            // complete before exiting the application.
            for (int i = 0; i < NUMTHREADS; i++) {
                threadArray[i].join();
            }
        } catch (Exception e) {
            System.err.println("TxnGuide: " + e.toString());
            e.printStackTrace();
        } finally {
            closeEnv();
        }
        System.out.println("All done.");
    }
```
Tokens:
Raw