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"
"github.com/FerretDB/FerretDB/ferretdb"
)
func main() {
f, err := ferretdb.New(&ferretdb.Config{
Listener: ferretdb.ListenerConfig{
TCP: "127.0.0.1:17027",
},
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 struct{})
go func() {
log.Print(f.Run(ctx))
close(done)
}()
uri := f.MongoDBURI()
fmt.Println(uri)
// Use MongoDB URI as usual. For example:
//
// import "go.mongodb.org/mongo-driver/mongo"
//
// [...]
//
// mongo.Connect(ctx, options.Client().ApplyURI(uri))
cancel()
<-done
}
Output: mongodb://127.0.0.1:17027/
Example (Tls) ¶
package main
import (
"context"
"fmt"
"log"
"path/filepath"
"github.com/FerretDB/FerretDB/ferretdb"
)
func main() {
certPath := filepath.Join("..", "build", "certs", "server-cert.pem")
keyPath := filepath.Join("..", "build", "certs", "server-key.pem")
caPath := filepath.Join("..", "build", "certs", "rootCA-cert.pem")
f, err := ferretdb.New(&ferretdb.Config{
Listener: ferretdb.ListenerConfig{
TLS: "127.0.0.1:17028",
TLSCertFile: certPath,
TLSKeyFile: keyPath,
TLSCAFile: caPath,
},
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 struct{})
go func() {
log.Print(f.Run(ctx))
close(done)
}()
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()
<-done
}
Output: mongodb://127.0.0.1:17028/?tls=true
Example (Unix) ¶
package main
import (
"context"
"fmt"
"log"
"github.com/FerretDB/FerretDB/ferretdb"
)
func main() {
f, err := ferretdb.New(&ferretdb.Config{
Listener: ferretdb.ListenerConfig{
Unix: "/tmp/ferretdb.sock",
},
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 struct{})
go func() {
log.Print(f.Run(ctx))
close(done)
}()
uri := f.MongoDBURI()
fmt.Println(uri)
// Use MongoDB URI as usual.
cancel()
<-done
}
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, it uses the default global logger.
Logger *zap.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 (*FerretDB) MongoDBURI ¶
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 ¶
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.
Source Files