ferretdb

package
v1.24.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 28, 2024 License: Apache-2.0 Imports: 10 Imported by: 7

Documentation

Overview

Package ferretdb provides embeddable FerretDB implementation.

See github.com/FerretDB/FerretDB/build/version package documentation for information about Go build tags that affect this package.

Example (Tcp)
package main

import (
	"context"
	"fmt"
	"log"
	"log/slog"

	"github.com/FerretDB/FerretDB/ferretdb"
)

func main() {
	f, err := ferretdb.New(&ferretdb.Config{
		Listener: ferretdb.ListenerConfig{
			TCP: "127.0.0.1:17027",
		},
		Logger:        slog.With("component", "ferretdb"),
		Handler:       "postgresql",
		PostgreSQLURL: "postgres://127.0.0.1:5432/ferretdb",
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx, cancel := context.WithCancel(context.Background())
	done := make(chan error)

	go func() {
		done <- f.Run(ctx)
	}()

	uri := f.MongoDBURI()
	fmt.Println(uri)

	// Use MongoDB URI as usual.
	// For example:
	//
	// import "go.mongodb.org/mongo-driver/mongo"
	// import "go.mongodb.org/mongo-driver/mongo/options"
	//
	// [...]
	//
	// mongo.Connect(ctx, options.Client().ApplyURI(uri))

	cancel()

	err = <-done
	if err != nil {
		log.Fatal(err)
	}

}
Output:

mongodb://127.0.0.1:17027/
Example (Tls)
package main

import (
	"context"
	"fmt"
	"log"
	"log/slog"
	"path/filepath"

	"github.com/FerretDB/FerretDB/ferretdb"
	"github.com/FerretDB/FerretDB/internal/util/testutil"
)

func main() {
	f, err := ferretdb.New(&ferretdb.Config{
		Listener: ferretdb.ListenerConfig{
			TLS:         "127.0.0.1:17028",
			TLSCertFile: filepath.Join(testutil.BuildCertsDir, "server-cert.pem"),
			TLSKeyFile:  filepath.Join(testutil.BuildCertsDir, "server-key.pem"),
			TLSCAFile:   filepath.Join(testutil.BuildCertsDir, "rootCA-cert.pem"),
		},
		Logger:        slog.With("component", "ferretdb"),
		Handler:       "postgresql",
		PostgreSQLURL: "postgres://127.0.0.1:5432/ferretdb",
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx, cancel := context.WithCancel(context.Background())
	done := make(chan error)

	go func() {
		done <- f.Run(ctx)
	}()

	uri := f.MongoDBURI()
	fmt.Println(uri)

	// Use MongoDB URI as usual.
	// To connect to TLS listener, set TLS config.
	// For example:
	//
	// import "go.mongodb.org/mongo-driver/mongo"
	// import "go.mongodb.org/mongo-driver/mongo/options"
	//
	// [...]
	//
	// mongo.Connect(ctx, options.Client().ApplyURI(uri))

	cancel()

	err = <-done
	if err != nil {
		log.Fatal(err)
	}

}
Output:

mongodb://127.0.0.1:17028/?tls=true
Example (Unix)
package main

import (
	"context"
	"fmt"
	"log"
	"log/slog"

	"github.com/FerretDB/FerretDB/ferretdb"
)

func main() {
	f, err := ferretdb.New(&ferretdb.Config{
		Listener: ferretdb.ListenerConfig{
			Unix: "/tmp/ferretdb.sock",
		},
		Logger:        slog.With("component", "ferretdb"),
		Handler:       "postgresql",
		PostgreSQLURL: "postgres://127.0.0.1:5432/ferretdb",
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx, cancel := context.WithCancel(context.Background())
	done := make(chan error)

	go func() {
		done <- f.Run(ctx)
	}()

	uri := f.MongoDBURI()
	fmt.Println(uri)

	// Use MongoDB URI as usual.
	// For example:
	//
	// import "go.mongodb.org/mongo-driver/mongo"
	// import "go.mongodb.org/mongo-driver/mongo/options"
	//
	// [...]
	//
	// mongo.Connect(ctx, options.Client().ApplyURI(uri))

	cancel()

	err = <-done
	if err != nil {
		log.Fatal(err)
	}

}
Output:

mongodb://%2Ftmp%2Fferretdb.sock/

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	Listener ListenerConfig

	// Logger to use; if nil, `slog.Default()` is used.
	Logger *slog.Logger

	// Handler to use; one of `postgresql` or `sqlite`.
	Handler string

	// PostgreSQL connection string for `postgresql` handler.
	// See:
	//   - https://pkg.go.dev/github.com/jackc/pgx/v5/pgxpool#ParseConfig
	//   - https://pkg.go.dev/github.com/jackc/pgx/v5#ParseConfig
	//   - https://pkg.go.dev/github.com/jackc/pgx/v5/pgconn#ParseConfig
	PostgreSQLURL string // For example: `postgres://hostname:5432/ferretdb`.

	// SQLite URI (directory) for `sqlite` handler.
	// See https://www.sqlite.org/uri.html.
	SQLiteURL string // For example: `file:data/`.
}

Config represents FerretDB configuration.

type FerretDB

type FerretDB struct {
	// contains filtered or unexported fields
}

FerretDB represents an instance of embeddable FerretDB implementation.

func New

func New(config *Config) (*FerretDB, error)

New creates a new instance of embeddable FerretDB implementation.

func (*FerretDB) MongoDBURI

func (f *FerretDB) MongoDBURI() string

MongoDBURI returns MongoDB URI for this FerretDB instance.

TCP's connection string is returned if both TCP and Unix listeners are enabled. TLS is preferred over both.

func (*FerretDB) Run

func (f *FerretDB) Run(ctx context.Context) error

Run runs FerretDB until ctx is canceled.

When this method returns, listener and all connections, as well as handler are closed.

It is required to run this method in order to initialize the listeners with their respective IP address and port. Calling methods which require the listener's address (eg: *FerretDB.MongoDBURI requires it for configuring its Host URL) before calling this method might result in a deadlock.

type ListenerConfig added in v0.7.1

type ListenerConfig struct {
	// Listen TCP address.
	// If empty, TCP listener is disabled.
	TCP string

	// Listen Unix domain socket path.
	// If empty, Unix listener is disabled.
	Unix string

	// Listen TLS address.
	// If empty, TLS listener is disabled.
	TLS string

	// Server certificate path.
	TLSCertFile string

	// Server key path.
	TLSKeyFile string

	// Root CA certificate path.
	TLSCAFile string
}

ListenerConfig represents listener configuration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL