db

Documentation

Index

• Constants
• func NewErrAlreadyExists(msg string) error
• type Account
• type Admin
• type Basic
• type DB
• type Domain
• type Emoji
• type ErrAlreadyExists
  • func (e *ErrAlreadyExists) Error() string
• type Error
• type Instance
• type Media
• type Mention
• type Notification
• type Relationship
• type Session
• type Status
• type Timeline
• type Where

Constants

const (
	// DBTypePostgres represents an underlying POSTGRES database type.
	DBTypePostgres string = "POSTGRES"
)

Functions

func NewErrAlreadyExists

func NewErrAlreadyExists(msg string) error

Types

type Account

type Account interface {
	// GetAccountByID returns one account with the given ID, or an error if something goes wrong.
	GetAccountByID(ctx context.Context, id string) (*gtsmodel.Account, Error)

	// GetAccountByURI returns one account with the given URI, or an error if something goes wrong.
	GetAccountByURI(ctx context.Context, uri string) (*gtsmodel.Account, Error)

	// GetAccountByURL returns one account with the given URL, or an error if something goes wrong.
	GetAccountByURL(ctx context.Context, uri string) (*gtsmodel.Account, Error)

	// UpdateAccount updates one account by ID.
	UpdateAccount(ctx context.Context, account *gtsmodel.Account) (*gtsmodel.Account, Error)

	// GetLocalAccountByUsername returns an account on this instance by its username.
	GetLocalAccountByUsername(ctx context.Context, username string) (*gtsmodel.Account, Error)

	// GetAccountFaves fetches faves/likes created by the target accountID.
	GetAccountFaves(ctx context.Context, accountID string) ([]*gtsmodel.StatusFave, Error)

	// GetAccountStatusesCount is a shortcut for the common action of counting statuses produced by accountID.
	CountAccountStatuses(ctx context.Context, accountID string) (int, Error)

	// GetAccountStatuses is a shortcut for getting the most recent statuses. accountID is optional, if not provided
	// then all statuses will be returned. If limit is set to 0, the size of the returned slice will not be limited. This can
	// be very memory intensive so you probably shouldn't do this!
	// In case of no entries, a 'no entries' error will be returned
	GetAccountStatuses(ctx context.Context, accountID string, limit int, excludeReplies bool, excludeReblogs bool, maxID string, minID string, pinnedOnly bool, mediaOnly bool, publicOnly bool) ([]*gtsmodel.Status, Error)

	GetAccountBlocks(ctx context.Context, accountID string, maxID string, sinceID string, limit int) ([]*gtsmodel.Account, string, string, Error)

	// GetAccountLastPosted simply gets the timestamp of the most recent post by the account.
	//
	// The returned time will be zero if account has never posted anything.
	GetAccountLastPosted(ctx context.Context, accountID string) (time.Time, Error)

	// SetAccountHeaderOrAvatar sets the header or avatar for the given accountID to the given media attachment.
	SetAccountHeaderOrAvatar(ctx context.Context, mediaAttachment *gtsmodel.MediaAttachment, accountID string) Error

	// GetInstanceAccount returns the instance account for the given domain.
	// If domain is empty, this instance account will be returned.
	GetInstanceAccount(ctx context.Context, domain string) (*gtsmodel.Account, Error)
}

Account contains functions related to account getting/setting/creation.

type Admin

type Admin interface {
	// IsUsernameAvailable checks whether a given username is available on our domain.
	// Returns an error if the username is already taken, or something went wrong in the db.
	IsUsernameAvailable(ctx context.Context, username string) (bool, Error)

	// IsEmailAvailable checks whether a given email address for a new account is available to be used on our domain.
	// Return an error if:
	// A) the email is already associated with an account
	// B) we block signups from this email domain
	// C) something went wrong in the db
	IsEmailAvailable(ctx context.Context, email string) (bool, Error)

	// NewSignup creates a new user in the database with the given parameters.
	// By the time this function is called, it should be assumed that all the parameters have passed validation!
	NewSignup(ctx context.Context, username string, reason string, requireApproval bool, email string, password string, signUpIP net.IP, locale string, appID string, emailVerified bool, admin bool) (*gtsmodel.User, Error)

	// CreateInstanceAccount creates an account in the database with the same username as the instance host value.
	// Ie., if the instance is hosted at 'example.org' the instance user will have a username of 'example.org'.
	// This is needed for things like serving files that belong to the instance and not an individual user/account.
	CreateInstanceAccount(ctx context.Context) Error

	// CreateInstanceInstance creates an instance in the database with the same domain as the instance host value.
	// Ie., if the instance is hosted at 'example.org' the instance will have a domain of 'example.org'.
	// This is needed for things like serving instance information through /api/v1/instance
	CreateInstanceInstance(ctx context.Context) Error
}

Admin contains functions related to instance administration (new signups etc).

type Basic

type Basic interface {
	// CreateTable creates a table for the given interface.
	// For implementations that don't use tables, this can just return nil.
	CreateTable(ctx context.Context, i interface{}) Error

	// CreateAllTables creates *all* tables necessary for the running of GoToSocial.
	// Because it uses the 'if not exists' parameter it is safe to run against a GtS that's already been initialized.
	CreateAllTables(ctx context.Context) Error

	// DropTable drops the table for the given interface.
	// For implementations that don't use tables, this can just return nil.
	DropTable(ctx context.Context, i interface{}) Error

	// Stop should stop and close the database connection cleanly, returning an error if this is not possible.
	// If the database implementation doesn't need to be stopped, this can just return nil.
	Stop(ctx context.Context) Error

	// IsHealthy should return nil if the database connection is healthy, or an error if not.
	IsHealthy(ctx context.Context) Error

	// GetByID gets one entry by its id. In a database like postgres, this might be the 'id' field of the entry,
	// for other implementations (for example, in-memory) it might just be the key of a map.
	// The given interface i will be set to the result of the query, whatever it is. Use a pointer or a slice.
	// In case of no entries, a 'no entries' error will be returned
	GetByID(ctx context.Context, id string, i interface{}) Error

	// GetWhere gets one entry where key = value. This is similar to GetByID but allows the caller to specify the
	// name of the key to select from.
	// The given interface i will be set to the result of the query, whatever it is. Use a pointer or a slice.
	// In case of no entries, a 'no entries' error will be returned
	GetWhere(ctx context.Context, where []Where, i interface{}) Error

	// GetAll will try to get all entries of type i.
	// The given interface i will be set to the result of the query, whatever it is. Use a pointer or a slice.
	// In case of no entries, a 'no entries' error will be returned
	GetAll(ctx context.Context, i interface{}) Error

	// Put simply stores i. It is up to the implementation to figure out how to store it, and using what key.
	// The given interface i will be set to the result of the query, whatever it is. Use a pointer or a slice.
	Put(ctx context.Context, i interface{}) Error

	// UpdateByPrimaryKey updates all values of i based on its primary key.
	// The given interface i will be set to the result of the query, whatever it is. Use a pointer or a slice.
	UpdateByPrimaryKey(ctx context.Context, i interface{}) Error

	// UpdateWhere updates column key of interface i with the given value, where the given parameters apply.
	UpdateWhere(ctx context.Context, where []Where, key string, value interface{}, i interface{}) Error

	// DeleteByID removes i with id id.
	// If i didn't exist anyway, then no error should be returned.
	DeleteByID(ctx context.Context, id string, i interface{}) Error

	// DeleteWhere deletes i where key = value
	// If i didn't exist anyway, then no error should be returned.
	DeleteWhere(ctx context.Context, where []Where, i interface{}) Error
}

Basic wraps basic database functionality.

type DB

type DB interface {
	Account
	Admin
	Basic
	Domain
	Emoji
	Instance
	Media
	Mention
	Notification
	Relationship
	Session
	Status
	Timeline

	// TagStringsToTags takes a slice of deduplicated, lowercase tags in the form "somehashtag", which have been
	// used in a status. It takes the id of the account that wrote the status, and the id of the status itself, and then
	// returns a slice of *model.Tag corresponding to the given tags. If the tag already exists in database, that tag
	// will be returned. Otherwise a pointer to a new tag struct will be created and returned.
	//
	// Note: this func doesn't/shouldn't do any manipulation of the tags in the DB, it's just for checking
	// if they exist in the db already, and conveniently returning them, or creating new tag structs.
	TagStringsToTags(ctx context.Context, tags []string, originAccountID string) ([]*gtsmodel.Tag, error)

	// EmojiStringsToEmojis takes a slice of deduplicated, lowercase emojis in the form ":emojiname:", which have been
	// used in a status. It takes the id of the account that wrote the status, and the id of the status itself, and then
	// returns a slice of *model.Emoji corresponding to the given emojis.
	//
	// Note: this func doesn't/shouldn't do any manipulation of the emoji in the DB, it's just for checking
	// if they exist in the db and conveniently returning them if they do.
	EmojiStringsToEmojis(ctx context.Context, emojis []string) ([]*gtsmodel.Emoji, error)
}

DB provides methods for interacting with an underlying database or other storage mechanism.

type Domain

type Domain interface {
	// IsDomainBlocked checks if an instance-level domain block exists for the given domain string (eg., `example.org`).
	IsDomainBlocked(ctx context.Context, domain string) (bool, Error)

	// AreDomainsBlocked checks if an instance-level domain block exists for any of the given domains strings, and returns true if even one is found.
	AreDomainsBlocked(ctx context.Context, domains []string) (bool, Error)

	// IsURIBlocked checks if an instance-level domain block exists for the `host` in the given URI (eg., `https://example.org/users/whatever`).
	IsURIBlocked(ctx context.Context, uri *url.URL) (bool, Error)

	// AreURIsBlocked checks if an instance-level domain block exists for any `host` in the given URI slice, and returns true if even one is found.
	AreURIsBlocked(ctx context.Context, uris []*url.URL) (bool, Error)
}

Domain contains DB functions related to domains and domain blocks.

type Emoji

type Emoji interface {
	// GetCustomEmojis gets all custom emoji for the instance
	GetCustomEmojis(ctx context.Context) ([]*gtsmodel.Emoji, Error)
}

Emoji contains functions for getting emoji in the database.

type ErrAlreadyExists

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

ErrAlreadyExists is returned when a caller tries to insert a database entry that already exists in the db.

func (*ErrAlreadyExists) Error

func (e *ErrAlreadyExists) Error() string

type Error

type Error error

Error denotes a database error.

var (
	// ErrNoEntries is returned when a caller expected an entry for a query, but none was found.
	ErrNoEntries Error = fmt.Errorf("no entries")
	// ErrMultipleEntries is returned when a caller expected ONE entry for a query, but multiples were found.
	ErrMultipleEntries Error = fmt.Errorf("multiple entries")
	// ErrUnknown denotes an unknown database error.
	ErrUnknown Error = fmt.Errorf("unknown error")
)

type Instance

type Instance interface {
	// CountInstanceUsers returns the number of known accounts registered with the given domain.
	CountInstanceUsers(ctx context.Context, domain string) (int, Error)

	// CountInstanceStatuses returns the number of known statuses posted from the given domain.
	CountInstanceStatuses(ctx context.Context, domain string) (int, Error)

	// CountInstanceDomains returns the number of known instances known that the given domain federates with.
	CountInstanceDomains(ctx context.Context, domain string) (int, Error)

	// GetInstanceAccounts returns a slice of accounts from the given instance, arranged by ID.
	GetInstanceAccounts(ctx context.Context, domain string, maxID string, limit int) ([]*gtsmodel.Account, Error)
}

Instance contains functions for instance-level actions (counting instance users etc.).

type Media

type Media interface {
	// GetAttachmentByID gets a single attachment by its ID
	GetAttachmentByID(ctx context.Context, id string) (*gtsmodel.MediaAttachment, Error)
	// GetRemoteOlderThan gets limit n remote media attachments older than the given olderThan time.
	// These will be returned in order of attachment.created_at descending (newest to oldest in other words).
	//
	// The selected media attachments will be those with both a URL and a RemoteURL filled in.
	// In other words, media attachments that originated remotely, and that we currently have cached locally.
	GetRemoteOlderThan(ctx context.Context, olderThan time.Time, limit int) ([]*gtsmodel.MediaAttachment, Error)
	// GetAvatarsAndHeaders fetches limit n avatars and headers with an id < maxID. These headers
	// and avis may be in use or not; the caller should check this if it's important.
	GetAvatarsAndHeaders(ctx context.Context, maxID string, limit int) ([]*gtsmodel.MediaAttachment, Error)
}

Media contains functions related to creating/getting/removing media attachments.

type Mention

type Mention interface {
	// GetMention gets a single mention by ID
	GetMention(ctx context.Context, id string) (*gtsmodel.Mention, Error)

	// GetMentions gets multiple mentions.
	GetMentions(ctx context.Context, ids []string) ([]*gtsmodel.Mention, Error)
}

Mention contains functions for getting/creating mentions in the database.

type Notification

type Notification interface {
	// GetNotifications returns a slice of notifications that pertain to the given accountID.
	//
	// Returned notifications will be ordered ID descending (ie., highest/newest to lowest/oldest).
	GetNotifications(ctx context.Context, accountID string, limit int, maxID string, sinceID string) ([]*gtsmodel.Notification, Error)
	// GetNotification returns one notification according to its id.
	GetNotification(ctx context.Context, id string) (*gtsmodel.Notification, Error)
}

Notification contains functions for creating and getting notifications.

type Relationship

type Relationship interface {
	// IsBlocked checks whether account 1 has a block in place against account2.
	// If eitherDirection is true, then the function returns true if account1 blocks account2, OR if account2 blocks account1.
	IsBlocked(ctx context.Context, account1 string, account2 string, eitherDirection bool) (bool, Error)

	// GetBlock returns the block from account1 targeting account2, if it exists, or an error if it doesn't.
	//
	// Because this is slower than Blocked, only use it if you need the actual Block struct for some reason,
	// not if you're just checking for the existence of a block.
	GetBlock(ctx context.Context, account1 string, account2 string) (*gtsmodel.Block, Error)

	// GetRelationship retrieves the relationship of the targetAccount to the requestingAccount.
	GetRelationship(ctx context.Context, requestingAccount string, targetAccount string) (*gtsmodel.Relationship, Error)

	// IsFollowing returns true if sourceAccount follows target account, or an error if something goes wrong while finding out.
	IsFollowing(ctx context.Context, sourceAccount *gtsmodel.Account, targetAccount *gtsmodel.Account) (bool, Error)

	// IsFollowRequested returns true if sourceAccount has requested to follow target account, or an error if something goes wrong while finding out.
	IsFollowRequested(ctx context.Context, sourceAccount *gtsmodel.Account, targetAccount *gtsmodel.Account) (bool, Error)

	// IsMutualFollowing returns true if account1 and account2 both follow each other, or an error if something goes wrong while finding out.
	IsMutualFollowing(ctx context.Context, account1 *gtsmodel.Account, account2 *gtsmodel.Account) (bool, Error)

	// AcceptFollowRequest moves a follow request in the database from the follow_requests table to the follows table.
	// In other words, it should create the follow, and delete the existing follow request.
	//
	// It will return the newly created follow for further processing.
	AcceptFollowRequest(ctx context.Context, originAccountID string, targetAccountID string) (*gtsmodel.Follow, Error)

	// RejectFollowRequest fetches a follow request from the database, and then deletes it.
	//
	// The deleted follow request will be returned so that further processing can be done on it.
	RejectFollowRequest(ctx context.Context, originAccountID string, targetAccountID string) (*gtsmodel.FollowRequest, Error)

	// GetAccountFollowRequests returns all follow requests targeting the given account.
	GetAccountFollowRequests(ctx context.Context, accountID string) ([]*gtsmodel.FollowRequest, Error)

	// GetAccountFollows returns a slice of follows owned by the given accountID.
	GetAccountFollows(ctx context.Context, accountID string) ([]*gtsmodel.Follow, Error)

	// CountAccountFollows returns the amount of accounts that the given accountID is following.
	//
	// If localOnly is set to true, then only follows from *this instance* will be returned.
	CountAccountFollows(ctx context.Context, accountID string, localOnly bool) (int, Error)

	// GetAccountFollowedBy fetches follows that target given accountID.
	//
	// If localOnly is set to true, then only follows from *this instance* will be returned.
	GetAccountFollowedBy(ctx context.Context, accountID string, localOnly bool) ([]*gtsmodel.Follow, Error)

	// CountAccountFollowedBy returns the amounts that the given ID is followed by.
	CountAccountFollowedBy(ctx context.Context, accountID string, localOnly bool) (int, Error)
}

Relationship contains functions for getting or modifying the relationship between two accounts.

type Session

type Session interface {
	GetSession(ctx context.Context) (*gtsmodel.RouterSession, Error)
}

Session handles getting/creation of router sessions.

type Status

type Status interface {
	// GetStatusByID returns one status from the database, with no rel fields populated, only their linking ID / URIs
	GetStatusByID(ctx context.Context, id string) (*gtsmodel.Status, Error)

	// GetStatusByURI returns one status from the database, with no rel fields populated, only their linking ID / URIs
	GetStatusByURI(ctx context.Context, uri string) (*gtsmodel.Status, Error)

	// GetStatusByURL returns one status from the database, with no rel fields populated, only their linking ID / URIs
	GetStatusByURL(ctx context.Context, uri string) (*gtsmodel.Status, Error)

	// PutStatus stores one status in the database.
	PutStatus(ctx context.Context, status *gtsmodel.Status) Error

	// CountStatusReplies returns the amount of replies recorded for a status, or an error if something goes wrong
	CountStatusReplies(ctx context.Context, status *gtsmodel.Status) (int, Error)

	// CountStatusReblogs returns the amount of reblogs/boosts recorded for a status, or an error if something goes wrong
	CountStatusReblogs(ctx context.Context, status *gtsmodel.Status) (int, Error)

	// CountStatusFaves returns the amount of faves/likes recorded for a status, or an error if something goes wrong
	CountStatusFaves(ctx context.Context, status *gtsmodel.Status) (int, Error)

	// GetStatusParents gets the parent statuses of a given status.
	//
	// If onlyDirect is true, only the immediate parent will be returned.
	GetStatusParents(ctx context.Context, status *gtsmodel.Status, onlyDirect bool) ([]*gtsmodel.Status, Error)

	// GetStatusChildren gets the child statuses of a given status.
	//
	// If onlyDirect is true, only the immediate children will be returned.
	GetStatusChildren(ctx context.Context, status *gtsmodel.Status, onlyDirect bool, minID string) ([]*gtsmodel.Status, Error)

	// IsStatusFavedBy checks if a given status has been faved by a given account ID
	IsStatusFavedBy(ctx context.Context, status *gtsmodel.Status, accountID string) (bool, Error)

	// IsStatusRebloggedBy checks if a given status has been reblogged/boosted by a given account ID
	IsStatusRebloggedBy(ctx context.Context, status *gtsmodel.Status, accountID string) (bool, Error)

	// IsStatusMutedBy checks if a given status has been muted by a given account ID
	IsStatusMutedBy(ctx context.Context, status *gtsmodel.Status, accountID string) (bool, Error)

	// IsStatusBookmarkedBy checks if a given status has been bookmarked by a given account ID
	IsStatusBookmarkedBy(ctx context.Context, status *gtsmodel.Status, accountID string) (bool, Error)

	// GetStatusFaves returns a slice of faves/likes of the given status.
	// This slice will be unfiltered, not taking account of blocks and whatnot, so filter it before serving it back to a user.
	GetStatusFaves(ctx context.Context, status *gtsmodel.Status) ([]*gtsmodel.StatusFave, Error)

	// GetStatusReblogs returns a slice of statuses that are a boost/reblog of the given status.
	// This slice will be unfiltered, not taking account of blocks and whatnot, so filter it before serving it back to a user.
	GetStatusReblogs(ctx context.Context, status *gtsmodel.Status) ([]*gtsmodel.Status, Error)
}

Status contains functions for getting statuses, creating statuses, and checking various other fields on statuses.

type Timeline

type Timeline interface {
	// GetHomeTimeline returns a slice of statuses from accounts that are followed by the given account id.
	//
	// Statuses should be returned in descending order of when they were created (newest first).
	GetHomeTimeline(ctx context.Context, accountID string, maxID string, sinceID string, minID string, limit int, local bool) ([]*gtsmodel.Status, Error)

	// GetPublicTimeline fetches the account's PUBLIC timeline -- ie., posts and replies that are public.
	// It will use the given filters and try to return as many statuses as possible up to the limit.
	//
	// Statuses should be returned in descending order of when they were created (newest first).
	GetPublicTimeline(ctx context.Context, accountID string, maxID string, sinceID string, minID string, limit int, local bool) ([]*gtsmodel.Status, Error)

	// GetFavedTimeline fetches the account's FAVED timeline -- ie., posts and replies that the requesting account has faved.
	// It will use the given filters and try to return as many statuses as possible up to the limit.
	//
	// Note that unlike the other GetTimeline functions, the returned statuses will be arranged by their FAVE id, not the STATUS id.
	// In other words, they'll be returned in descending order of when they were faved by the requesting user, not when they were created.
	//
	// Also note the extra return values, which correspond to the nextMaxID and prevMinID for building Link headers.
	GetFavedTimeline(ctx context.Context, accountID string, maxID string, minID string, limit int) ([]*gtsmodel.Status, string, string, Error)
}

Timeline contains functionality for retrieving home/public/faved etc timelines for an account.

type Where

type Where struct {
	// The table to search on.
	Key string
	// The value to match.
	Value interface{}
	// Whether the value (if a string) should be case sensitive or not.
	// Defaults to false.
	CaseInsensitive bool
	// If set, reverse the where.
	// `WHERE k = v` becomes `WHERE k != v`.
	// `WHERE k IS NULL` becomes `WHERE k IS NOT NULL`
	Not bool
}

Where allows the caller of the DB to specify Where parameters.