database

Documentation

Overview

Package database provides database and Hasura metadata operations.

Index

• func Backup(ctx context.Context, cfg *config.Config, outputPath string) error
• func HasuraApplyMetadata(ctx context.Context, cfg *config.Config, projectDir string) error
• func HasuraDiffMetadata(ctx context.Context, cfg *config.Config, projectDir string) ([]string, error)
• func HasuraExportMetadata(ctx context.Context, cfg *config.Config) ([]byte, error)
• func HasuraExportToYAML(ctx context.Context, cfg *config.Config, projectDir string) (string, error)
• func HasuraReloadMetadata(ctx context.Context, cfg *config.Config) error
• func HasuraValidatePermissions(ctx context.Context, cfg *config.Config) ([]string, error)
• func InitializeDatabase(ctx context.Context, cfg *config.Config) error
• func MigrateDown(ctx context.Context, cfg *config.Config) error
• func MigrateUp(ctx context.Context, cfg *config.Config, plugin string) (int, error)
• func PendingMigrations(ctx context.Context, cfg *config.Config, plugin string) ([]string, error)
• func ResetChecksum(ctx context.Context, cfg *config.Config, migrationID string) error
• func Restore(ctx context.Context, cfg *config.Config, inputPath string) error
• func Seed(ctx context.Context, cfg *config.Config, file string) error
• func SeedFilter(seedFiles []string, dbEnvSeeds string, currentEnv string) []string
• type ChecksumMismatch
  • func VerifyChecksums(ctx context.Context, cfg *config.Config, plugin string) ([]ChecksumMismatch, error)
• type MigrationRecord
• type MigrationStatus
  • func MigrateStatus(ctx context.Context, cfg *config.Config) ([]MigrationStatus, error)

Functions

func Backup

func Backup(ctx context.Context, cfg *config.Config, outputPath string) error

Backup runs pg_dump inside the project's postgres container and streams the output directly to a file on disk. The custom format (-Fc) is used so the dump can be restored with pg_restore.

If outputPath is empty, a timestamped filename is generated under a "backups/" directory relative to the current working directory.

func HasuraApplyMetadata

func HasuraApplyMetadata(ctx context.Context, cfg *config.Config, projectDir string) error

HasuraApplyMetadata applies Hasura metadata from projectDir.

It supports two metadata formats:

1. YAML directory format (standard Hasura CLI): projectDir/hasura/metadata/ Tables use !include directives referencing individual YAML files. This format is detected first. If the hasura CLI binary is in PATH it is used directly (handles all YAML features). Otherwise nSelf resolves !include directives in Go and sends the result to the metadata API.

2. JSON format (legacy nSelf): projectDir/hasura/metadata.json Sent directly to the replace_metadata API.

If neither exists, reload_metadata is called (safe/idempotent).

func HasuraDiffMetadata

func HasuraDiffMetadata(ctx context.Context, cfg *config.Config, projectDir string) ([]string, error)

HasuraDiffMetadata compares live metadata against on-disk YAML files. Returns a list of keys that differ. Empty list means no drift.

func HasuraExportMetadata

func HasuraExportMetadata(ctx context.Context, cfg *config.Config) ([]byte, error)

HasuraExportMetadata retrieves the current metadata from Hasura as raw JSON bytes.

func HasuraExportToYAML

func HasuraExportToYAML(ctx context.Context, cfg *config.Config, projectDir string) (string, error)

HasuraExportToYAML exports live Hasura metadata to a git-friendly sorted YAML directory structure under {projectDir}/hasura/metadata/. Returns the output directory path.

func HasuraReloadMetadata

func HasuraReloadMetadata(ctx context.Context, cfg *config.Config) error

HasuraReloadMetadata tells Hasura to reload its metadata from the internal catalog, picking up any changes to tracked tables, relationships, or permissions.

func HasuraValidatePermissions

func HasuraValidatePermissions(ctx context.Context, cfg *config.Config) ([]string, error)

HasuraValidatePermissions checks that every tenant-scoped table tracked by Hasura has permissions for tenant_member and tenant_admin roles. Returns a list of tables missing required permissions.

func InitializeDatabase

func InitializeDatabase(ctx context.Context, cfg *config.Config) error

InitializeDatabase waits for PostgreSQL to become ready, then creates the database, schemas, grants, and required extensions. This is Phase 3 of the nself startup sequence.

Steps:

1. Wait for pg_isready (max 60s, check every 1s)
2. CREATE DATABASE IF NOT EXISTS
3. CREATE SCHEMA IF NOT EXISTS auth, storage, public
4. GRANT ALL ON SCHEMA auth, storage, public TO user
5. CREATE EXTENSION IF NOT EXISTS pgcrypto, citext

func MigrateDown

func MigrateDown(ctx context.Context, cfg *config.Config) error

MigrateDown reverts the most recently applied migration. It looks for a corresponding .down.sql file next to the original migration.

func MigrateUp

func MigrateUp(ctx context.Context, cfg *config.Config, plugin string) (int, error)

MigrateUp applies all pending migrations from the migrations directory. If plugin is non-empty, only that plugin's migrations are applied. Uses advisory locks to prevent concurrent runs, records SHA-256 checksums, and detects non-transactional statements (CREATE INDEX CONCURRENTLY) to run them outside a transaction. Returns the count of migrations applied.

func PendingMigrations

func PendingMigrations(ctx context.Context, cfg *config.Config, plugin string) ([]string, error)

PendingMigrations returns the list of migration names that have not yet been applied.

func ResetChecksum

func ResetChecksum(ctx context.Context, cfg *config.Config, migrationID string) error

ResetChecksum updates the stored checksum for a migration to match the current file on disk.

func Restore

func Restore(ctx context.Context, cfg *config.Config, inputPath string) error

Restore streams a pg_dump custom-format file into the project's postgres container via pg_restore. The file contents are piped to docker exec's stdin, avoiding the need to copy the dump into the container first.

func Seed

func Seed(ctx context.Context, cfg *config.Config, file string) error

Seed executes SQL seed files against the postgres database. If file is specified, only that file is run. If file is empty, all *.sql files in the seeds/ directory are executed in alphabetical order.

func SeedFilter

func SeedFilter(seedFiles []string, dbEnvSeeds string, currentEnv string) []string

SeedFilter returns the subset of seedFiles that should run in currentEnv. DB_ENV_SEEDS format: "dev:file1.sql,staging:file2.sql" Files not mentioned in dbEnvSeeds run in all environments. Files mentioned in dbEnvSeeds only run when their env matches currentEnv.

Types

type ChecksumMismatch

type ChecksumMismatch struct {
	ID       string
	Name     string
	Expected string // stored in DB
	Actual   string // computed from disk
}

ChecksumMismatch describes a migration whose on-disk checksum differs from the recorded value.

func VerifyChecksums

func VerifyChecksums(ctx context.Context, cfg *config.Config, plugin string) ([]ChecksumMismatch, error)

VerifyChecksums compares on-disk migration checksums against stored values. Returns a list of mismatches (empty means all good).

type MigrationRecord

type MigrationRecord struct {
	ID         string
	Name       string
	Checksum   string
	AppliedAt  string
	AppliedBy  string
	DurationMs int
	RolledBack bool
}

MigrationRecord holds the state of a migration from nself_ops.migrations.

type MigrationStatus

type MigrationStatus struct {
	Name      string
	Applied   bool
	Timestamp time.Time
}

MigrationStatus describes the state of a single migration file.

func MigrateStatus

func MigrateStatus(ctx context.Context, cfg *config.Config) ([]MigrationStatus, error)

MigrateStatus returns the status of all known migrations (applied and pending). It merges on-disk migration files with the schema_versions table, so orphaned migrations (applied but no longer on disk) are also reported.