sqlite

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Jan 31, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultMaxConnections = 5

DefaultMaxConnections is the default connection pool size for SQLite. This should match the DatabaseWorkers configuration (default 5).

Variables

This section is empty.

Functions

func NewFromCmdlineOptions added in v0.18.0 

func NewFromCmdlineOptions() plugin.Plugin

Types

type CommitTimestamp added in v0.4.0 

type CommitTimestamp struct {
	ID        uint `gorm:"primarykey"`
	Timestamp int64
}

CommitTimestamp represents the sqlite table used to track the current commit timestamp

func (CommitTimestamp) TableName added in v0.4.0 

func (CommitTimestamp) TableName() string

type MetadataStoreSqlite added in v0.4.0 

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

MetadataStoreSqlite stores all data in sqlite. Data may not be persisted

func New 

func New(
	dataDir string,
	logger *slog.Logger,
	promRegistry prometheus.Registerer,
) (*MetadataStoreSqlite, error)

New creates a new database

func NewWithOptions added in v0.18.0 

func NewWithOptions(opts ...SqliteOptionFunc) (*MetadataStoreSqlite, error)

NewWithOptions creates a new database with options

func (*MetadataStoreSqlite) AddUtxos added in v0.8.0 

func (d *MetadataStoreSqlite) AddUtxos(
	utxos []models.UtxoSlot,
	txn types.Txn,
) error

AddUtxos saves a batch of UTxOs directly

func (*MetadataStoreSqlite) AutoMigrate added in v0.4.0 

func (d *MetadataStoreSqlite) AutoMigrate(dst ...any) error

AutoMigrate wraps the gorm AutoMigrate

func (*MetadataStoreSqlite) BeginTxn added in v0.19.0 

func (d *MetadataStoreSqlite) BeginTxn() (types.Txn, error)

BeginTxn starts a transaction and returns the handle with an error. Callers that prefer explicit error handling can use this instead of Transaction().

func (*MetadataStoreSqlite) Close added in v0.4.0 

func (d *MetadataStoreSqlite) Close() error

Close gets the database handle from our MetadataStore and closes it

func (*MetadataStoreSqlite) Create added in v0.4.0 

func (d *MetadataStoreSqlite) Create(value any) *gorm.DB

Create creates a record

func (*MetadataStoreSqlite) DB added in v0.4.0 

func (d *MetadataStoreSqlite) DB() *gorm.DB

DB returns the database handle

func (*MetadataStoreSqlite) DeleteBlockNoncesBeforeSlot added in v0.11.0 

func (d *MetadataStoreSqlite) DeleteBlockNoncesBeforeSlot(
	slotNumber uint64,
	txn types.Txn,
) error

DeleteBlockNoncesBeforeSlot deletes block_nonce records with slot less than the specified value

func (*MetadataStoreSqlite) DeleteBlockNoncesBeforeSlotWithoutCheckpoints added in v0.11.0 

func (d *MetadataStoreSqlite) DeleteBlockNoncesBeforeSlotWithoutCheckpoints(
	slotNumber uint64,
	txn types.Txn,
) error

DeleteBlockNoncesBeforeSlotWithoutCheckpoints deletes block_nonce records with slot < given value AND is_checkpoint = false

func (*MetadataStoreSqlite) DeleteCertificatesAfterSlot added in v0.21.0 

func (d *MetadataStoreSqlite) DeleteCertificatesAfterSlot(
	slot uint64,
	txn types.Txn,
) error

DeleteCertificatesAfterSlot removes all certificate records added after the given slot. This is used during chain rollbacks to undo certificate state changes. All deletions are performed atomically within a transaction to ensure consistency.

func (*MetadataStoreSqlite) DeletePParamUpdatesAfterSlot added in v0.21.0 

func (d *MetadataStoreSqlite) DeletePParamUpdatesAfterSlot(
	slot uint64,
	txn types.Txn,
) error

DeletePParamUpdatesAfterSlot removes protocol parameter update records added after the given slot.

func (*MetadataStoreSqlite) DeletePParamsAfterSlot added in v0.21.0 

func (d *MetadataStoreSqlite) DeletePParamsAfterSlot(
	slot uint64,
	txn types.Txn,
) error

DeletePParamsAfterSlot removes protocol parameter records added after the given slot.

func (*MetadataStoreSqlite) DeleteTransactionsAfterSlot added in v0.21.0 

func (d *MetadataStoreSqlite) DeleteTransactionsAfterSlot(
	slot uint64,
	txn types.Txn,
) error

DeleteTransactionsAfterSlot removes transaction records added after the given slot. Child records are automatically removed via CASCADE constraints. UTXO hash-based foreign keys (spent_at_tx_id, collateral_by_tx_id, referenced_by_tx_id) are NULLed out before deleting transactions to prevent orphaned references.

func (*MetadataStoreSqlite) DeleteUtxo added in v0.4.2 

func (d *MetadataStoreSqlite) DeleteUtxo(
	utxoId models.UtxoId,
	txn types.Txn,
) error

func (*MetadataStoreSqlite) DeleteUtxos added in v0.4.2 

func (d *MetadataStoreSqlite) DeleteUtxos(
	utxos []models.UtxoId,
	txn types.Txn,
) error

func (*MetadataStoreSqlite) DeleteUtxosAfterSlot added in v0.4.4 

func (d *MetadataStoreSqlite) DeleteUtxosAfterSlot(
	slot uint64,
	txn types.Txn,
) error

func (*MetadataStoreSqlite) First added in v0.4.0 

func (d *MetadataStoreSqlite) First(args any) *gorm.DB

First returns the first DB entry

func (*MetadataStoreSqlite) GetAccount added in v0.6.0 

func (d *MetadataStoreSqlite) GetAccount(
	stakeKey []byte,
	includeInactive bool,
	txn types.Txn,
) (*models.Account, error)

GetAccount gets an account

func (*MetadataStoreSqlite) GetActivePoolRelays added in v0.21.0 

func (d *MetadataStoreSqlite) GetActivePoolRelays(
	txn types.Txn,
) ([]models.PoolRegistrationRelay, error)

GetActivePoolRelays returns all relays from currently active pools. A pool is considered active if it has a registration and either: - No retirement, or - The retirement epoch is in the future

Implementation note: This function loads all registrations and retirements per pool and filters in Go rather than using complex SQL JOINs. This approach is necessary because:

  1. GORM's Preload with Limit(1) applies the limit globally, not per-parent
  2. Determining the "latest" registration/retirement requires comparing added_slot values which is cumbersome in a single query
  3. The filtering logic (retirement epoch vs current epoch) is clearer in Go

For networks with thousands of pools, this may use significant memory. Future optimization could use raw SQL with window functions (ROW_NUMBER) or batch processing if memory becomes a concern.

func (*MetadataStoreSqlite) GetAssetByPolicyAndName added in v0.18.0 

func (d *MetadataStoreSqlite) GetAssetByPolicyAndName(
	policyId lcommon.Blake2b224,
	assetName []byte,
	txn types.Txn,
) (models.Asset, error)

GetAssetByPolicyAndName returns an asset by policy ID and asset name

func (*MetadataStoreSqlite) GetAssetsByPolicy added in v0.18.0 

func (d *MetadataStoreSqlite) GetAssetsByPolicy(
	policyId lcommon.Blake2b224,
	txn types.Txn,
) ([]models.Asset, error)

GetAssetsByPolicy returns all assets for a given policy ID

func (*MetadataStoreSqlite) GetAssetsByUTxO added in v0.18.0 

func (d *MetadataStoreSqlite) GetAssetsByUTxO(
	txId []byte,
	idx uint32,
	txn types.Txn,
) ([]models.Asset, error)

GetAssetsByUTxO returns all assets for a given UTxO using transaction ID and output index

func (*MetadataStoreSqlite) GetBlockNonce added in v0.11.0 

func (d *MetadataStoreSqlite) GetBlockNonce(
	point ocommon.Point,
	txn types.Txn,
) ([]byte, error)

GetBlockNonce retrieves the block nonce for a specific block

func (*MetadataStoreSqlite) GetCommitTimestamp added in v0.4.0 

func (d *MetadataStoreSqlite) GetCommitTimestamp() (int64, error)

func (*MetadataStoreSqlite) GetDatum added in v0.9.0 

func (d *MetadataStoreSqlite) GetDatum(
	hash lcommon.Blake2b256,
	txn types.Txn,
) (*models.Datum, error)

GetDatum returns a datum by its hash

func (*MetadataStoreSqlite) GetDrep added in v0.7.0 

func (d *MetadataStoreSqlite) GetDrep(
	cred []byte,
	includeInactive bool,
	txn types.Txn,
) (*models.Drep, error)

GetDrep gets a drep

func (*MetadataStoreSqlite) GetEpochSummary added in v0.21.0 

func (d *MetadataStoreSqlite) GetEpochSummary(
	epoch uint64,
	txn types.Txn,
) (*models.EpochSummary, error)

GetEpochSummary retrieves an epoch summary by epoch number

func (*MetadataStoreSqlite) GetEpochs added in v0.6.0 

func (d *MetadataStoreSqlite) GetEpochs(
	txn types.Txn,
) ([]models.Epoch, error)

GetEpochs returns the list of epochs

func (*MetadataStoreSqlite) GetEpochsByEra added in v0.4.3 

func (d *MetadataStoreSqlite) GetEpochsByEra(
	eraId uint,
	txn types.Txn,
) ([]models.Epoch, error)

GetEpochsByEra returns the list of epochs by era

func (*MetadataStoreSqlite) GetLatestEpochSummary added in v0.21.0 

func (d *MetadataStoreSqlite) GetLatestEpochSummary(
	txn types.Txn,
) (*models.EpochSummary, error)

GetLatestEpochSummary retrieves the most recent epoch summary

func (*MetadataStoreSqlite) GetPParamUpdates added in v0.4.2 

func (d *MetadataStoreSqlite) GetPParamUpdates(
	epoch uint64,
	txn types.Txn,
) ([]models.PParamUpdate, error)

GetPParamUpdates returns a list of protocol parameter updates for a given epoch. Updates are returned in descending order by ID (most recent first).

func (*MetadataStoreSqlite) GetPParams added in v0.4.2 

func (d *MetadataStoreSqlite) GetPParams(
	epoch uint64,
	txn types.Txn,
) ([]models.PParams, error)

GetPParams returns a list of protocol parameters for a given epoch. If there are no pparams for the specified epoch, it will return the most recent pparams before the specified epoch

func (*MetadataStoreSqlite) GetPool added in v0.6.0 

func (d *MetadataStoreSqlite) GetPool(
	pkh lcommon.PoolKeyHash,
	includeInactive bool,
	txn types.Txn,
) (*models.Pool, error)

GetPool gets a pool

func (*MetadataStoreSqlite) GetPoolRegistrations added in v0.4.2 

func (d *MetadataStoreSqlite) GetPoolRegistrations(
	pkh lcommon.PoolKeyHash,
	txn types.Txn,
) ([]lcommon.PoolRegistrationCertificate, error)

GetPoolRegistrations returns pool registration certificates

func (*MetadataStoreSqlite) GetPoolStakeSnapshot added in v0.21.0 

func (d *MetadataStoreSqlite) GetPoolStakeSnapshot(
	epoch uint64,
	snapshotType string,
	poolKeyHash []byte,
	txn types.Txn,
) (*models.PoolStakeSnapshot, error)

GetPoolStakeSnapshot retrieves a specific pool's stake snapshot

func (*MetadataStoreSqlite) GetPoolStakeSnapshotsByEpoch added in v0.21.0 

func (d *MetadataStoreSqlite) GetPoolStakeSnapshotsByEpoch(
	epoch uint64,
	snapshotType string,
	txn types.Txn,
) ([]*models.PoolStakeSnapshot, error)

GetPoolStakeSnapshotsByEpoch retrieves all pool stake snapshots for an epoch

func (*MetadataStoreSqlite) GetScript added in v0.18.0 

func (d *MetadataStoreSqlite) GetScript(
	hash lcommon.ScriptHash,
	txn types.Txn,
) (*models.Script, error)

GetScript returns the script content by its hash

func (*MetadataStoreSqlite) GetStakeRegistrations added in v0.4.2 

func (d *MetadataStoreSqlite) GetStakeRegistrations(
	stakingKey []byte,
	txn types.Txn,
) ([]lcommon.StakeRegistrationCertificate, error)

GetStakeRegistrations returns stake registration certificates

func (*MetadataStoreSqlite) GetTip added in v0.4.2 

func (d *MetadataStoreSqlite) GetTip(
	txn types.Txn,
) (ocommon.Tip, error)

GetTip returns the current metadata Tip as ocommon.Tip

func (*MetadataStoreSqlite) GetTotalActiveStake added in v0.21.0 

func (d *MetadataStoreSqlite) GetTotalActiveStake(
	epoch uint64,
	snapshotType string,
	txn types.Txn,
) (uint64, error)

GetTotalActiveStake returns the sum of all pool stakes for an epoch

func (*MetadataStoreSqlite) GetTransactionByHash added in v0.18.0 

func (d *MetadataStoreSqlite) GetTransactionByHash(
	hash []byte,
	txn types.Txn,
) (*models.Transaction, error)

GetTransactionByHash returns a transaction by its hash

func (*MetadataStoreSqlite) GetUtxo added in v0.4.2 

func (d *MetadataStoreSqlite) GetUtxo(
	txId []byte,
	idx uint32,
	txn types.Txn,
) (*models.Utxo, error)

GetUtxo returns a Utxo by reference

func (*MetadataStoreSqlite) GetUtxosAddedAfterSlot added in v0.4.3 

func (d *MetadataStoreSqlite) GetUtxosAddedAfterSlot(
	slot uint64,
	txn types.Txn,
) ([]models.Utxo, error)

GetUtxosAddedAfterSlot returns a list of Utxos added after a given slot

func (*MetadataStoreSqlite) GetUtxosBatch added in v0.21.0 

func (d *MetadataStoreSqlite) GetUtxosBatch(
	refs []UtxoRef,
	txn types.Txn,
) (map[string]*models.Utxo, error)

GetUtxosBatch retrieves multiple UTXOs by their references in a single query. Returns a map keyed by "txid:outputidx" for easy lookup. Large batches are automatically chunked to avoid SQLite expression limits.

func (*MetadataStoreSqlite) GetUtxosByAddress added in v0.4.2 

func (d *MetadataStoreSqlite) GetUtxosByAddress(
	addr ledger.Address,
	txn types.Txn,
) ([]models.Utxo, error)

GetUtxosByAddress returns a list of Utxos

func (*MetadataStoreSqlite) GetUtxosByAssets added in v0.21.0 

func (d *MetadataStoreSqlite) GetUtxosByAssets(
	policyId []byte,
	assetName []byte,
	txn types.Txn,
) ([]models.Utxo, error)

GetUtxosByAssets returns a list of Utxos that contain the specified assets policyId: the policy ID of the asset (required) assetName: the asset name (pass nil to match all assets under the policy, or empty []byte{} to match assets with empty names)

func (*MetadataStoreSqlite) GetUtxosDeletedBeforeSlot added in v0.4.3 

func (d *MetadataStoreSqlite) GetUtxosDeletedBeforeSlot(
	slot uint64,
	limit int,
	txn types.Txn,
) ([]models.Utxo, error)

GetUtxosDeletedBeforeSlot returns a list of Utxos marked as deleted before a given slot

func (*MetadataStoreSqlite) Order added in v0.4.0 

func (d *MetadataStoreSqlite) Order(args any) *gorm.DB

Order orders a DB query

func (*MetadataStoreSqlite) RestoreAccountStateAtSlot added in v0.21.0 

func (d *MetadataStoreSqlite) RestoreAccountStateAtSlot(
	slot uint64,
	txn types.Txn,
) error

RestoreAccountStateAtSlot reverts account delegation state to the given slot. For accounts modified after the slot, this restores their Pool and Drep delegations to the state they had at the given slot, or deletes them if they were registered after that slot.

This implementation uses batch fetching to avoid N+1 query patterns: instead of querying certificates per-account, it fetches all relevant certificates for all affected accounts upfront (one query per table), then processes them in memory.

func (*MetadataStoreSqlite) RestoreDrepStateAtSlot added in v0.21.0 

func (d *MetadataStoreSqlite) RestoreDrepStateAtSlot(
	slot uint64,
	txn types.Txn,
) error

RestoreDrepStateAtSlot reverts DRep state to the given slot.

This function handles two cases for DReps modified after the rollback slot:

  1. DReps with no registration certificates at or before the slot are deleted (they didn't exist at that point in the chain).
  2. DReps with prior registrations have their state restored by examining all relevant certificates (registration, deregistration, update) and determining the correct Active status and anchor data.

The Active status follows these rules:

  • A registration certificate activates a DRep
  • A deregistration certificate deactivates a DRep
  • An update certificate can modify anchor data but cannot reactivate a deregistered DRep (per Cardano protocol rules)

The added_slot field is set to the slot of the most recent effective certificate that modified the DRep's state at or before the rollback slot.

This implementation uses batch fetching to avoid N+1 query patterns: instead of querying certificates per-DRep, it fetches all relevant certificates for all affected DReps upfront (one query per table), then processes them in memory.

func (*MetadataStoreSqlite) RestorePoolStateAtSlot added in v0.21.0 

func (d *MetadataStoreSqlite) RestorePoolStateAtSlot(
	slot uint64,
	txn types.Txn,
) error

RestorePoolStateAtSlot reverts pool state to the given slot.

This function handles two cases for pools:

  1. Pools with no registration certificates at or before the slot are deleted (they didn't exist at that point in the chain).
  2. Pools with at least one registration at or before the slot have their denormalized fields (Pledge, Cost, Margin, VrfKeyHash, RewardAccount) restored from the most recent such registration.

Child records are automatically removed via CASCADE constraints when pools are deleted. PoolRegistration records after the slot are removed separately by DeleteCertificatesAfterSlot.

This implementation uses batch fetching to avoid N+1 query patterns: instead of querying certificates per-pool, it fetches all relevant registrations for all affected pools upfront in one query with a JOIN to the certs table to get cert_index for deterministic same-slot ordering.

func (*MetadataStoreSqlite) SaveEpochSummary added in v0.21.0 

func (d *MetadataStoreSqlite) SaveEpochSummary(
	summary *models.EpochSummary,
	txn types.Txn,
) error

SaveEpochSummary saves an epoch summary

func (*MetadataStoreSqlite) SavePoolStakeSnapshot added in v0.21.0 

func (d *MetadataStoreSqlite) SavePoolStakeSnapshot(
	snapshot *models.PoolStakeSnapshot,
	txn types.Txn,
) error

SavePoolStakeSnapshot saves a pool stake snapshot

func (*MetadataStoreSqlite) SavePoolStakeSnapshots added in v0.21.0 

func (d *MetadataStoreSqlite) SavePoolStakeSnapshots(
	snapshots []*models.PoolStakeSnapshot,
	txn types.Txn,
) error

SavePoolStakeSnapshots saves multiple pool stake snapshots in batch

func (*MetadataStoreSqlite) SetAccount added in v0.6.0 

func (d *MetadataStoreSqlite) SetAccount(
	stakeKey, pkh, drep []byte,
	slot uint64,
	active bool,
	txn types.Txn,
) error

SetAccount saves an account

func (*MetadataStoreSqlite) SetBlockNonce added in v0.11.0 

func (d *MetadataStoreSqlite) SetBlockNonce(
	blockHash []byte,
	slotNumber uint64,
	nonce []byte,
	isCheckpoint bool,
	txn types.Txn,
) error

SetBlockNonce inserts a block nonce into the block_nonce table

func (*MetadataStoreSqlite) SetCommitTimestamp added in v0.4.0 

func (d *MetadataStoreSqlite) SetCommitTimestamp(
	timestamp int64,
	txn types.Txn,
) error

func (*MetadataStoreSqlite) SetDatum added in v0.9.0 

func (d *MetadataStoreSqlite) SetDatum(
	hash lcommon.Blake2b256,
	rawDatum []byte,
	addedSlot uint64,
	txn types.Txn,
) error

SetDatum saves a datum

func (*MetadataStoreSqlite) SetDrep added in v0.7.0 

func (d *MetadataStoreSqlite) SetDrep(
	cred []byte,
	slot uint64,
	url string,
	hash []byte,
	active bool,
	txn types.Txn,
) error

SetDrep saves a drep

func (*MetadataStoreSqlite) SetEpoch added in v0.4.2 

func (d *MetadataStoreSqlite) SetEpoch(
	slot, epoch uint64,
	nonce []byte,
	era, slotLength, lengthInSlots uint,
	txn types.Txn,
) error

SetEpoch saves an epoch

func (*MetadataStoreSqlite) SetPParamUpdate added in v0.4.2 

func (d *MetadataStoreSqlite) SetPParamUpdate(
	genesis, update []byte,
	slot, epoch uint64,
	txn types.Txn,
) error

SetPParamUpdate saves a protocol parameter update

func (*MetadataStoreSqlite) SetPParams added in v0.4.2 

func (d *MetadataStoreSqlite) SetPParams(
	params []byte,
	slot, epoch uint64,
	eraId uint,
	txn types.Txn,
) error

SetPParams saves protocol parameters

func (*MetadataStoreSqlite) SetTip added in v0.4.2 

func (d *MetadataStoreSqlite) SetTip(
	tip ochainsync.Tip,
	txn types.Txn,
) error

SetTip saves a tip

func (*MetadataStoreSqlite) SetTransaction added in v0.18.0 

func (d *MetadataStoreSqlite) SetTransaction(
	tx lcommon.Transaction,
	point ocommon.Point,
	idx uint32,
	certDeposits map[int]uint64,
	txn types.Txn,
) error

SetTransaction adds a new transaction to the database and processes all certificates

func (*MetadataStoreSqlite) SetUtxoDeletedAtSlot added in v0.4.4 

func (d *MetadataStoreSqlite) SetUtxoDeletedAtSlot(
	input ledger.TransactionInput,
	slot uint64,
	txn types.Txn,
) error

SetUtxoDeletedAtSlot marks a UTxO as deleted at the given slot

func (*MetadataStoreSqlite) SetUtxosNotDeletedAfterSlot added in v0.4.3 

func (d *MetadataStoreSqlite) SetUtxosNotDeletedAfterSlot(
	slot uint64,
	txn types.Txn,
) error

SetUtxosNotDeletedAfterSlot marks a list of Utxos as not deleted after a given slot

func (*MetadataStoreSqlite) Start added in v0.18.0 

func (d *MetadataStoreSqlite) Start() error

Start implements the plugin.Plugin interface

func (*MetadataStoreSqlite) Stop added in v0.18.0 

func (d *MetadataStoreSqlite) Stop() error

Stop implements the plugin.Plugin interface

func (*MetadataStoreSqlite) Transaction added in v0.4.0 

func (d *MetadataStoreSqlite) Transaction() types.Txn

Transaction creates a gorm transaction

func (*MetadataStoreSqlite) Where added in v0.4.0 

func (d *MetadataStoreSqlite) Where(
	query any,
	args ...any,
) *gorm.DB

Where constrains a DB query

type SqliteOptionFunc added in v0.18.0 

type SqliteOptionFunc func(*MetadataStoreSqlite)

func WithDataDir added in v0.18.0 

func WithDataDir(dataDir string) SqliteOptionFunc

WithDataDir specifies the data directory to use for storage

func WithLogger added in v0.18.0 

func WithLogger(logger *slog.Logger) SqliteOptionFunc

WithLogger specifies the logger object to use for logging messages

func WithMaxConnections added in v0.21.0 

func WithMaxConnections(maxConnections int) SqliteOptionFunc

WithMaxConnections specifies the maximum number of database connections. This should match the DatabaseWorkers configuration to avoid connection pool exhaustion or unnecessary contention on SQLite's lock infrastructure.

func WithPromRegistry added in v0.18.0 

func WithPromRegistry(
	registry prometheus.Registerer,
) SqliteOptionFunc

WithPromRegistry specifies the prometheus registry to use for metrics

type UtxoRef added in v0.21.0 

type UtxoRef struct {
	TxId      []byte
	OutputIdx uint32
}

UtxoRef represents a reference to a UTXO by transaction ID and output index

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.