wbtiger
/
foundationdb
mirror of https://github.com/apple/foundationdb.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2438 from ajbeamon/document-open-multiple-databases 

Add documentation about opening connections to multiple clusters
This commit is contained in:
Vishesh Yadav 2019-12-11 13:01:00 -08:00 committed by GitHub
parent b4ff66a722 d09e3e1d96
commit 1b93c10332
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 52 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
bindings/go/src/fdb/cluster.go
View File

@ -26,7 +26,7 @@ package fdb
// #include <foundationdb/fdb_c.h>
import "C"
// Deprecated: Use OpenDatabase or OpenDefault to obtain a database handle directly
// Deprecated: Use OpenDatabase or OpenDefault to obtain a database handle directly.
// Cluster is a handle to a FoundationDB cluster. Cluster is a lightweight
// object that may be efficiently copied, and is safe for concurrent use by
// multiple goroutines.
@ -34,7 +34,7 @@ type Cluster struct {
clusterFileName string
}
// Deprecated: Use OpenDatabase or OpenDefault to obtain a database handle directly
// Deprecated: Use OpenDatabase or OpenDefault to obtain a database handle directly.
// OpenDatabase returns a database handle from the FoundationDB cluster.
//
// The database name must be []byte("DB").

19
bindings/go/src/fdb/fdb.go
View File

@ -236,8 +236,12 @@ func StartNetwork() error {
const DefaultClusterFile string = ""
// OpenDefault returns a database handle to the FoundationDB cluster identified
// by the DefaultClusterFile on the current machine. The FoundationDB client
// networking engine will be initialized first, if necessary.
// by the DefaultClusterFile on the current machine.
//
// A single client can use this function multiple times to connect to different
// clusters simultaneously, with each invocation requiring its own cluster file.
// To connect to multiple clusters running at different, incompatible versions,
// the multi-version client API must be used.
func OpenDefault() (Database, error) {
return OpenDatabase(DefaultClusterFile)
}
@ -254,6 +258,11 @@ func MustOpenDefault() Database {
// Open returns a database handle to the FoundationDB cluster identified
// by the provided cluster file and database name.
//
// A single client can use this function multiple times to connect to different
// clusters simultaneously, with each invocation requiring its own cluster file.
// To connect to multiple clusters running at different, incompatible versions,
// the multi-version client API must be used.
func OpenDatabase(clusterFile string) (Database, error) {
networkMutex.Lock()
defer networkMutex.Unlock()
@ -283,6 +292,8 @@ func OpenDatabase(clusterFile string) (Database, error) {
return db, nil
}
// MustOpenDatabase is like OpenDatabase but panics if the default database cannot
// be opened.
func MustOpenDatabase(clusterFile string) Database {
db, err := OpenDatabase(clusterFile)
if err != nil {
@ -291,7 +302,7 @@ func MustOpenDatabase(clusterFile string) Database {
return db
}
// Deprecated: Use OpenDatabase instead
// Deprecated: Use OpenDatabase instead.
// The database name must be []byte("DB").
func Open(clusterFile string, dbName []byte) (Database, error) {
if bytes.Compare(dbName, []byte("DB")) != 0 {
@ -300,7 +311,7 @@ func Open(clusterFile string, dbName []byte) (Database, error) {
return OpenDatabase(clusterFile)
}
// Deprecated: Use MustOpenDatabase instead
// Deprecated: Use MustOpenDatabase instead.
// MustOpen is like Open but panics if the database cannot be opened.
func MustOpen(clusterFile string, dbName []byte) Database {
db, err := Open(clusterFile, dbName)

29
bindings/java/src/main/com/apple/foundationdb/FDB.java
View File

@ -292,9 +292,14 @@ public class FDB {
}
/**
* Initializes networking, connects with the
* <a href="/foundationdb/administration.html#default-cluster-file" target="_blank">default fdb.cluster file</a>,
* and opens the database.
* Initializes networking if required and connects to the cluster specified by the
* <a href="/foundationdb/administration.html#default-cluster-file" target="_blank">default fdb.cluster file</a>.<br>
* <br>
* A single client can use this function multiple times to connect to different
* clusters simultaneously, with each invocation requiring its own cluster file.
* To connect to multiple clusters running at different, incompatible versions,
* the <a href="/foundationdb/api-general.html#multi-version-client-api" target="_blank">multi-version client API</a>
* must be used.
*
* @return a {@code CompletableFuture} that will be set to a FoundationDB {@link Database}
*/
@ -303,8 +308,13 @@ public class FDB {
}
/**
* Initializes networking, connects to the cluster specified by {@code clusterFilePath}
* and opens the database.
* Initializes networking if required and connects to the cluster specified by {@code clusterFilePath}.<br>
* <br>
* A single client can use this function multiple times to connect to different
* clusters simultaneously, with each invocation requiring its own cluster file.
* To connect to multiple clusters running at different, incompatible versions,
* the <a href="/foundationdb/api-general.html#multi-version-client-api" target="_blank">multi-version client API</a>
* must be used.
*
* @param clusterFilePath the
* <a href="/foundationdb/administration.html#foundationdb-cluster-file" target="_blank">cluster file</a>
@ -319,8 +329,13 @@ public class FDB {
}
/**
* Initializes networking, connects to the cluster specified by {@code clusterFilePath}
* and opens the database.
* Initializes networking if required and connects to the cluster specified by {@code clusterFilePath}.<br>
* <br>
* A single client can use this function multiple times to connect to different
* clusters simultaneously, with each invocation requiring its own cluster file.
* To connect to multiple clusters running at different, incompatible versions,
* the <a href="/foundationdb/api-general.html#multi-version-client-api" target="_blank">multi-version client API</a>
* must be used.
*
* @param clusterFilePath the
* <a href="/foundationdb/administration.html#foundationdb-cluster-file" target="_blank">cluster file</a>

2
documentation/sphinx/source/api-c.rst
View File

@ -393,6 +393,8 @@ An |database-blurb1| Modifications to a database are performed via transactions.
Creates a new database connected the specified cluster. The caller assumes ownership of the :type:`FDBDatabase` object and must destroy it with :func:`fdb_database_destroy()`.
|fdb-open-blurb2|
``cluster_file_path``
A NULL-terminated string giving a local path of a :ref:`cluster file <foundationdb-cluster-file>` (often called 'fdb.cluster') which contains connection information for the FoundationDB cluster. If cluster_file_path is NULL or an empty string, then a :ref:`default cluster file <default-cluster-file>` will be used.

7
documentation/sphinx/source/api-common.rst.inc
View File

@ -456,8 +456,11 @@
Cancels |future-type-string| and its associated asynchronous operation. If called before the future is ready, attempts to access its value will |error-raise-type| an :ref:`operation_cancelled <developer-guide-error-codes>` |error-type|. Cancelling a future which is already ready has no effect. Note that even if a future is not ready, its associated asynchronous operation may have succesfully completed and be unable to be cancelled.
.. |fdb-open-blurb| replace::
Initializes the FoundationDB API and connects to the cluster specified by the :ref:`cluster file <foundationdb-cluster-file>`. This function is often called without any parameters, using only the defaults. If no cluster file is passed, FoundationDB automatically :ref:`determines a cluster file <specifying-a-cluster-file>` with which to connect to a cluster.
.. |fdb-open-blurb1| replace::
Connects to the cluster specified by the :ref:`cluster file <foundationdb-cluster-file>`. This function is often called without any parameters, using only the defaults. If no cluster file is passed, FoundationDB automatically :ref:`determines a cluster file <specifying-a-cluster-file>` with which to connect to a cluster.
.. |fdb-open-blurb2| replace::
A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file. To connect to multiple clusters running at different, incompatible versions, the :ref:`multi-version client API <multi-version-client-api>` must be used.
.. |fdb-transactional-unknown-result-note| replace::
In some failure scenarios, it is possible that your transaction will be executed twice. See :ref:`developer-guide-unknown-results` for more information.

4
documentation/sphinx/source/api-python.rst
View File

@ -111,7 +111,9 @@ After importing the ``fdb`` module and selecting an API version, you probably wa
.. function:: open( cluster_file=None, event_model=None )
|fdb-open-blurb|
|fdb-open-blurb1|
|fdb-open-blurb2|
.. param event_model:: Can be used to select alternate :ref:`api-python-event-models`

4
documentation/sphinx/source/api-ruby.rst
View File

@ -100,7 +100,9 @@ After requiring the ``FDB`` gem and selecting an API version, you probably want
.. function:: open( cluster_file=nil ) -> Database
|fdb-open-blurb|
|fdb-open-blurb1|
|fdb-open-blurb2|
.. global:: FDB.options