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 HasuraExportMetadata(ctx context.Context, cfg *config.Config) ([]byte, error)
• func HasuraReloadMetadata(ctx context.Context, cfg *config.Config) 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 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 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 HasuraExportMetadata

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

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

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 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. Each migration is executed within a transaction alongside its schema_versions record, so a failure rolls back cleanly. 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 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 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.