sqldb

Documentation

Overview

Package sqldb runs and manages connections for Encore applications.

Index

• func OneshotProxy(rc remote.RemoteClient, appSlug, envSlug string) (port int, passwd string, err error)
• func ProxyRemoteConn(ctx context.Context, rc remote.RemoteClient, frontend net.Conn, ...)
• type Cluster
  • func (c *Cluster) Create(ctx context.Context, appRoot string, md *meta.Data) error
  • func (c *Cluster) CreateAndMigrate(ctx context.Context, appRoot string, md *meta.Data) error
  • func (c *Cluster) GetDB(name string) (*DB, bool)
  • func (c *Cluster) Ready() <-chan struct{}
  • func (c *Cluster) Recreate(ctx context.Context, appRoot string, services []string, md *meta.Data) error
  • func (c *Cluster) Start(log runlog.Log) error
  • func (c *Cluster) Status(ctx context.Context) (*ClusterStatus, error)
• type ClusterManager
  • func NewClusterManager() *ClusterManager
  • func (cm *ClusterManager) Delete(ctx context.Context, clusterID string) error
  • func (cm *ClusterManager) Get(clusterID string) (*Cluster, bool)
  • func (cm *ClusterManager) Init(ctx context.Context, params *InitParams) *Cluster
  • func (cm *ClusterManager) PreauthProxyConn(frontend net.Conn, clusterID string) error
  • func (cm *ClusterManager) ProxyConn(frontend net.Conn, waitForSetup bool) error
  • func (cm *ClusterManager) ServeProxy(ln net.Listener) error
• type ClusterStatus
• type ContainerStatus
• type DB
  • func (db *DB) CloseConns()
  • func (db *DB) Create(ctx context.Context) error
  • func (db *DB) Drop(ctx context.Context) error
  • func (db *DB) Migrate(ctx context.Context, appRoot string, svc *meta.Service) (err error)
  • func (db *DB) Ready() <-chan struct{}
  • func (db *DB) Setup(ctx context.Context, appRoot string, svc *meta.Service, migrate, recreate bool) (err error)
• type InitParams

Functions

func OneshotProxy

func OneshotProxy(rc remote.RemoteClient, appSlug, envSlug string) (port int, passwd string, err error)

OneshotProxy listens on a random port for a single connection, and proxies that connection to a remote db. It reports the one-time password and port to use. Once a connection has been established, it stops listening.

func ProxyRemoteConn

func ProxyRemoteConn(ctx context.Context, rc remote.RemoteClient, frontend net.Conn, passwd, appSlug, envSlug string)

ProxyRemoteConn proxies a frontend to the remote database pointed at by appSlug and envSlug. The passwd is what we expect the frontend to provide to authenticate the connection.

Types

type Cluster

type Cluster struct {
	ID    string // cluster ID
	Memfs bool   // use an an in-memory filesystem?

	HostPort string // available after Ready() is done

	// Ctx is canceled when the cluster is being torn down.
	Ctx context.Context
	// contains filtered or unexported fields
}

Cluster represents a running database Cluster.

func (*Cluster) Create

func (c *Cluster) Create(ctx context.Context, appRoot string, md *meta.Data) error

Create creates the given databases.

func (*Cluster) CreateAndMigrate

func (c *Cluster) CreateAndMigrate(ctx context.Context, appRoot string, md *meta.Data) error

CreateAndMigrate creates and migrates the given databases.

func (*Cluster) GetDB

func (c *Cluster) GetDB(name string) (*DB, bool)

GetDB gets the database with the given name.

func (*Cluster) Ready

func (c *Cluster) Ready() <-chan struct{}

Ready returns a channel that is closed when the cluster is up and running.

func (*Cluster) Recreate

func (c *Cluster) Recreate(ctx context.Context, appRoot string, services []string, md *meta.Data) error

Recreate recreates the databases for the given services. If services is the nil slice it recreates all databases.

func (*Cluster) Start

func (c *Cluster) Start(log runlog.Log) error

Start creates the container if necessary and starts it. If the cluster is already running it does nothing.

func (*Cluster) Status

func (c *Cluster) Status(ctx context.Context) (*ClusterStatus, error)

Status reports the status of the cluster.

type ClusterManager

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

A ClusterManager manages running local sqldb clusters.

func NewClusterManager

func NewClusterManager() *ClusterManager

NewClusterManager creates a new ClusterManager.

func (*ClusterManager) Delete

func (cm *ClusterManager) Delete(ctx context.Context, clusterID string) error

Delete forcibly deletes the cluster.

func (*ClusterManager) Get

func (cm *ClusterManager) Get(clusterID string) (*Cluster, bool)

Get retrieves the cluster keyed by id.

func (*ClusterManager) Init

func (cm *ClusterManager) Init(ctx context.Context, params *InitParams) *Cluster

Init initializes a database cluster but does not start it. If the cluster already exists it is returned. It does not perform any database migrations.

func (*ClusterManager) PreauthProxyConn

func (cm *ClusterManager) PreauthProxyConn(frontend net.Conn, clusterID string) error

PreauthProxyConn is a pre-authenticated proxy conn directly specifically to the given cluster.

func (*ClusterManager) ProxyConn

func (cm *ClusterManager) ProxyConn(frontend net.Conn, waitForSetup bool) error

ProxyConn authenticates and proxies a conn to the appropriate database cluster and database. If waitForSetup is true, it will wait for initial setup to complete before proxying the connection.

func (*ClusterManager) ServeProxy

func (cm *ClusterManager) ServeProxy(ln net.Listener) error

ServeProxy serves the database proxy using the given listener.

type ClusterStatus

type ClusterStatus struct {
	// Status is the status of the underlying container.
	Status ContainerStatus
	// HostPort is the host and port for connecting to the database.
	// It is only set when Status == Running.
	HostPort string
}

ClusterStatus rerepsents the status of a database cluster.

type ContainerStatus

type ContainerStatus string

ContainerStatus represents the status of a container.

const (
	// Running indicates the cluster container is running.
	Running ContainerStatus = "running"
	// Stopped indicates the container cluster exists but is not running.
	Stopped ContainerStatus = "stopped"
	// NotFound indicates the container cluster does not exist.
	NotFound ContainerStatus = "notfound"
)

type DB

type DB struct {
	Name    string // database name
	Cluster *Cluster

	// Ctx is canceled when the database is being torn down.
	Ctx context.Context
	// contains filtered or unexported fields
}

DB represents a single database instance within a cluster.

func (*DB) CloseConns

func (db *DB) CloseConns()

CloseConns closes all connections to this database through the dbproxy, and prevents future ones from being established.

func (*DB) Create

func (db *DB) Create(ctx context.Context) error

Create creates the database in the cluster if it does not already exist. It reports whether the database was initialized for the first time in this process.

func (*DB) Drop

func (db *DB) Drop(ctx context.Context) error

Drop drops the database in the cluster if it exists.

func (*DB) Migrate

func (db *DB) Migrate(ctx context.Context, appRoot string, svc *meta.Service) (err error)

Migrate migrates the database.

func (*DB) Ready

func (db *DB) Ready() <-chan struct{}

Ready returns a channel that is closed when the database is up and running.

func (*DB) Setup

func (db *DB) Setup(ctx context.Context, appRoot string, svc *meta.Service, migrate, recreate bool) (err error)

Setup sets up the database, (re)creating it if necessary and running schema migrations.

type InitParams

type InitParams struct {
	// ClusterID is the unique id of the cluster.
	ClusterID string

	// Meta is the metadata used to initialize databases.
	// If nil no databases are initialized.
	Meta *meta.Data

	// Memfs, if true, configures the database container to use an
	// in-memory filesystem as opposed to persisting the database to disk.
	Memfs bool

	// Reinit forces all databases to be reinitialized, even if they already exist.
	Reinit bool
}

InitParams are the params to (*ClusterManager).Init.