d1

package
v0.296.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const (
	ErrCodeVirtualTable        = "VIRTUAL_TABLE"
	ErrCodeMissingInput        = "MISSING_INPUT"
	ErrCodeMissingTool         = "MISSING_TOOL"
	ErrCodeInvalidInput        = "INVALID_INPUT"
	ErrCodeImportFailed        = "IMPORT_FAILED"
	ErrCodeVerifyFailed        = "VERIFY_FAILED"
	ErrCodeNotFound            = "NOT_FOUND"
	ErrCodePrereqFailed        = "PREREQ_FAILED"
	ErrCodeLintBlocked         = "LINT_BLOCKED"
	ErrCodeDestinationConflict = "DESTINATION_CONFLICT"
	ErrCodeStatePersistFailed  = "STATE_PERSIST_FAILED"
)

ErrCode constants for structured errors.

View Source
const (
	NotifyEventStarting  = "starting"
	NotifyEventProgress  = "progress"
	NotifyEventImported  = "imported"
	NotifyEventVerifying = "verifying"
	NotifyEventVerified  = "verified"
	NotifyEventComplete  = "complete"
	NotifyEventFailed    = "failed"
)

D1 import Slack notification event names.

View Source
const (
	MethodPgloader = "pgloader"
	MethodPsql     = "psql" // schema via psql; data via pgloader (dumps under 1GB)
)
View Source
const (
	ImportStageConnecting    = "connecting"
	ImportStageSQLiteStaging = "sqlite_staging"
	ImportStageSchema        = "schema"
	ImportStagePgloader      = "pgloader"
	ImportStageIndexes       = "indexes"
	ImportStageSequences     = "sequences"
)

Import stage names for progress reporting.

View Source
const (
	VerifyStageRowCounts    = "row_counts"
	VerifyStageSequences    = "verify_sequences"
	VerifyStageBoolean      = "boolean_columns"
	VerifyStageFingerprints = "fingerprints"
	VerifyStageSampleRows   = "sample_rows"
)

Verify stage names for progress reporting.

View Source
const (
	SeverityError   = "error"
	SeverityWarning = "warning"
	SeverityInfo    = "info"
)

Severity levels for lint/plan issues.

View Source
const (
	PhasePlanned   = "planned"
	PhaseImporting = "importing"
	PhaseImported  = "imported"
	PhaseVerified  = "verified"
	PhaseFailed    = "failed"
	PhaseComplete  = "complete"
)

Migration phases persisted in local state.

Variables

This section is empty.

Functions

func BuildSQLiteFromDump

func BuildSQLiteFromDump(ctx context.Context, dumpPath, sqlitePath string) error

BuildSQLiteFromDump always rebuilds sqlite from the dump (tests and forced refresh).

func CLICommandTarget

func CLICommandTarget(database, branch string) string

CLICommandTarget formats database and branch for pscale import d1 command examples.

func Complete

func Complete(org, database, branch, migrationID string, api NotifyAPIConfig) error

Complete marks a migration as finished in local state.

func CompleteSlackMessage

func CompleteSlackMessage(skippedTables []string, orms []string) string

CompleteSlackMessage returns a short Slack-friendly completion line.

func ConvertCreateStatement

func ConvertCreateStatement(sqliteDDL string) string

ConvertCreateStatement converts a raw SQLite CREATE TABLE line to Postgres (for tests).

func ConvertSchema

func ConvertSchema(inputPath, outputPath string) (int, error)

ConvertSchema converts SQLite CREATE TABLE statements to PostgreSQL DDL.

func CountInsertRows

func CountInsertRows(path string) (map[string]int, error)

CountInsertRows estimates row counts per table from INSERT statements.

func CountPostgresRows

func CountPostgresRows(ctx context.Context, destURI string, tables []string) (map[string]int64, error)

CountPostgresRows counts rows in public schema tables.

func CountSQLiteRows

func CountSQLiteRows(ctx context.Context, sqlitePath string, tables []string) (map[string]int64, error)

CountSQLiteRows counts rows using sqlite3 CLI.

func DefaultSQLitePath

func DefaultSQLitePath(dumpPath string) string

DefaultSQLitePath returns a sqlite path adjacent to the dump.

func DoctorReadinessError

func DoctorReadinessError(result *DoctorResult) error

DoctorReadinessError summarizes failed prerequisite checks for doctor/start.

func EnsureSQLiteFromDump

func EnsureSQLiteFromDump(ctx context.Context, dumpPath, sqlitePath string) error

EnsureSQLiteFromDump loads dump SQL into sqlite unless a fresh-enough database already exists.

func ErrLintBlocked

func ErrLintBlocked(reason string) error

ErrLintBlocked returns a structured error when lint errors block import.

func FileSize

func FileSize(path string) (int64, error)

FileSize returns the size of a file in bytes.

func FindPgloader

func FindPgloader() (string, error)

FindPgloader returns pgloader path.

func FindSQLite3

func FindSQLite3() (string, error)

FindSQLite3 returns sqlite3 path.

func FormatProgressMessage

func FormatProgressMessage(p ImportProgress) string

FormatProgressMessage returns a human-readable progress line for CLI and Slack.

func IsORMMetadataTable

func IsORMMetadataTable(name string) bool

IsORMMetadataTable reports whether a table holds ORM/framework migration bookkeeping that should not be imported into Postgres.

func NormalizeInputPath

func NormalizeInputPath(path string) (string, error)

NormalizeInputPath validates path and returns an absolute path for stable state comparisons.

func NotifyImportEvent

func NotifyImportEvent(api NotifyAPIConfig, org, database, branch, migrationID, event string, extra importNotificationPayload)

NotifyImportEvent posts a D1 import lifecycle event to api-bb asynchronously. Progress updates use this path; lifecycle and failure events should use NotifyImportEventSync.

func NotifyImportEventSync

func NotifyImportEventSync(api NotifyAPIConfig, org, database, branch, migrationID, event string, extra importNotificationPayload)

NotifyImportEventSync waits briefly for api-bb to accept the notification. Used for lifecycle boundaries and failures so Slack is reported before the CLI exits.

func ORMMetadataRule

func ORMMetadataRule(name string) *ormMetadataRule

ORMMetadataRule returns the matching ORM metadata rule, if any.

func OpenPostgres

func OpenPostgres(uri string) (*sql.DB, error)

OpenPostgres opens a PostgreSQL connection.

func PgloaderLoadTables

func PgloaderLoadTables(inputPath string) ([]string, error)

PgloaderLoadTables returns non-ORM tables in FK-safe load order.

func PrintHumanResponse

func PrintHumanResponse(p *printer.Printer, resp Response)

PrintHumanResponse writes a human-readable success response via the shared printer.

func PrintStartPreview

func PrintStartPreview(p *printer.Printer, prepared *ImportPrepareResult)

PrintStartPreview writes a human-readable lint/plan summary before import confirmation.

func ResetImportedSequences

func ResetImportedSequences(ctx context.Context, destURI, inputPath string) error

ResetImportedSequences aligns identity sequences with MAX(column) after pgloader import. Per-table pgloader runs may leave sequences at their initial value; setval is idempotent.

func ResolveDestURI

func ResolveDestURI(ctx context.Context, psClient *ps.Client, opts ImportOptions) (string, func() error, error)

ResolveDestURI creates a short-lived Postgres role and returns a connection string.

func ResolveMigrationDBName

func ResolveMigrationDBName(org, database, branch, migrationID, dbName string, dbNameExplicit bool) string

ResolveMigrationDBName returns the Postgres database name for import/verify flows. When dbNameExplicit is false and migration state records db_name, that value wins over the CLI default.

func ResolveVerifyDBName

func ResolveVerifyDBName(opts VerifyOptions, dbNameExplicit bool) string

ResolveVerifyDBName returns the Postgres database name for verify. When dbNameExplicit is false and migration state records a db_name, that value is preferred over the CLI default.

func SavePlan

func SavePlan(plan *PlanResult) error

SavePlan persists plan state for later import/verify.

func SaveState

func SaveState(state *MigrationState) error

SaveState is a package-level helper using the default store.

func SetMigrationPhase

func SetMigrationPhase(org, database, branch, migrationID, phase string) error

SetMigrationPhase updates the phase on existing migration state.

func Teardown

func Teardown(org, database, branch, migrationID string, api NotifyAPIConfig) error

Teardown is deprecated; use Complete.

func ValidateInputPath

func ValidateInputPath(path string) (string, error)

ValidateInputPath ensures a user-supplied path is safe to read.

Types

type CastRule

type CastRule struct {
	SourceType string `json:"source_type"`
	TargetType string `json:"target_type"`
	Using      string `json:"using,omitempty"`
	Tables     string `json:"tables,omitempty"`
}

CastRule maps SQLite types to Postgres casts for pgloader.

type ColumnSamples

type ColumnSamples map[string]map[string][]string

ColumnSamples holds sampled INSERT values per table/column.

func SampleColumnValues

func SampleColumnValues(path string, tables []TableSchema) (ColumnSamples, error)

SampleColumnValues reads INSERT statements and collects non-null literal values.

type ColumnSchema

type ColumnSchema struct {
	Name          string
	Type          string
	PrimaryKey    bool
	AutoIncrement bool
	NotNull       bool
	Unique        bool
	DefaultValue  string
	ForeignKey    string
}

ColumnSchema holds parsed column metadata.

type CompleteResult

type CompleteResult struct {
	MigrationID      string   `json:"migration_id"`
	Status           string   `json:"status"`
	SkippedORMTables []string `json:"skipped_orm_tables,omitempty"`
}

CompleteResult is the data payload for import d1 complete.

type DefaultImportClient

type DefaultImportClient struct {
	Client *ps.Client
}

DefaultImportClient wraps planetscale client.

func (*DefaultImportClient) GetDatabase

func (c *DefaultImportClient) GetDatabase(ctx context.Context, org, database string) (*ps.Database, error)

type DoctorCheck

type DoctorCheck struct {
	Name        string `json:"name"`
	Status      string `json:"status"`
	Version     string `json:"version,omitempty"`
	Message     string `json:"message,omitempty"`
	Remediation string `json:"remediation,omitempty"`
}

DoctorCheck is a single prerequisite check.

type DoctorResult

type DoctorResult struct {
	Checks []DoctorCheck `json:"checks"`
	Ready  bool          `json:"ready"`
}

DoctorResult lists prerequisite checks.

func Doctor

func Doctor(ctx context.Context) (*DoctorResult, error)

Doctor runs prerequisite checks for D1 migration.

type ErrorInfo

type ErrorInfo struct {
	Code        string `json:"code"`
	Message     string `json:"message"`
	Remediation string `json:"remediation,omitempty"`
}

ErrorInfo is a structured CLI/MCP error.

type ImportClient

type ImportClient interface {
	GetDatabase(ctx context.Context, org, database string) (*ps.Database, error)
}

ImportClient abstracts PlanetScale API access for import.

type ImportOptions

type ImportOptions struct {
	Org            string
	Database       string
	Branch         string
	InputPath      string
	Method         string
	MigrationID    string
	DBName         string
	DBNameExplicit bool
	DryRun         bool
	DestURI        string // optional override for testing
	NotifyAPI      NotifyAPIConfig
	OnProgress     ImportProgressFunc
	// PgloaderVerbose emits full pgloader reports to stderr (defaults to false).
	PgloaderVerbose bool
	// contains filtered or unexported fields
}

ImportOptions configures D1 import into PlanetScale Postgres.

type ImportPrepareResult

type ImportPrepareResult struct {
	MigrationID   string      `json:"migration_id"`
	Method        string      `json:"method"`
	Lint          *LintResult `json:"lint"`
	Plan          *PlanResult `json:"plan"`
	CanProceed    bool        `json:"can_proceed"`
	BlockedReason string      `json:"blocked_reason,omitempty"`
}

ImportPrepareResult is lint + plan output used before and during import.

func PrepareImport

func PrepareImport(opts ImportOptions) (*ImportPrepareResult, error)

PrepareImport runs lint and resolves or creates a migration plan without touching Postgres.

type ImportProgress

type ImportProgress struct {
	Stage   string `json:"stage"`
	Current int    `json:"current,omitempty"`
	Total   int    `json:"total,omitempty"`
	Detail  string `json:"detail,omitempty"`
}

ImportProgress describes import or verify pipeline progress for CLI and agent feedback.

type ImportProgressFunc

type ImportProgressFunc func(ImportProgress)

ImportProgressFunc receives progress updates during import or verify.

type ImportResult

type ImportResult struct {
	MigrationID  string         `json:"migration_id"`
	Method       string         `json:"method"`
	DryRun       bool           `json:"dry_run"`
	TablesLoaded int            `json:"tables_loaded,omitempty"`
	Timings      *ImportTimings `json:"timings,omitempty"`
	Lint         *LintResult    `json:"lint,omitempty"`
	Plan         *PlanResult    `json:"plan,omitempty"`
	CanProceed   bool           `json:"can_proceed"`
}

ImportResult describes an import run.

func Import

func Import(ctx context.Context, psClient *ps.Client, client ImportClient, opts ImportOptions, prepared *ImportPrepareResult) (result *ImportResult, err error)

Import loads a D1 SQLite dump into PlanetScale Postgres. Pass prepared when the caller already ran PrepareImport (e.g. human confirm flow).

type ImportTimings

type ImportTimings struct {
	TotalMs         int64             `json:"total_ms"`
	SQLiteStagingMs int64             `json:"sqlite_staging_ms,omitempty"`
	SchemaMs        int64             `json:"schema_ms,omitempty"`
	PgloaderMs      int64             `json:"pgloader_ms,omitempty"`
	IndexBuildMs    int64             `json:"index_build_ms,omitempty"`
	SequenceResetMs int64             `json:"sequence_reset_ms,omitempty"`
	TableLoads      []TableLoadTiming `json:"table_loads,omitempty"`
}

ImportTimings breaks down import wall-clock time by phase.

func RunPgloader

func RunPgloader(ctx context.Context, opts PgloaderOptions) (ImportTimings, error)

RunPgloader loads SQLite into PostgreSQL using pgloader.

type IndexSchema

type IndexSchema struct {
	Name    string
	Table   string
	Unique  bool
	Columns string
	RawDDL  string
}

IndexSchema holds a parsed CREATE INDEX statement from a dump.

func ParseIndexes

func ParseIndexes(path string) ([]IndexSchema, error)

ParseIndexes extracts CREATE INDEX statements from a SQLite dump.

type Issue

type Issue struct {
	Code        string `json:"code"`
	Severity    string `json:"severity"`
	Table       string `json:"table,omitempty"`
	Column      string `json:"column,omitempty"`
	Message     string `json:"message,omitempty"`
	Remediation string `json:"remediation"`
}

Issue describes a migration concern with agent-friendly remediation.

type LintResult

type LintResult struct {
	InputPath    string   `json:"input_path"`
	TableCount   int      `json:"table_count"`
	ErrorCount   int      `json:"error_count"`
	WarningCount int      `json:"warning_count"`
	Issues       []Issue  `json:"issues"`
	Tables       []string `json:"tables"`
}

LintResult summarizes lint output.

func Lint

func Lint(inputPath string) (*LintResult, error)

Lint analyzes a SQLite dump for migration issues.

type MigrationError

type MigrationError struct {
	Info ErrorInfo
}

func (*MigrationError) Error

func (e *MigrationError) Error() string

type MigrationState

type MigrationState struct {
	MigrationID   string    `json:"migration_id"`
	Org           string    `json:"org"`
	Database      string    `json:"database"`
	Branch        string    `json:"branch"`
	InputPath     string    `json:"input_path"`
	SQLitePath    string    `json:"sqlite_path,omitempty"`
	DBName        string    `json:"db_name,omitempty"`
	Method        string    `json:"method,omitempty"`
	Phase         string    `json:"phase"`
	SchemaApplied bool      `json:"schema_applied,omitempty"`
	LoadedTables  []string  `json:"loaded_tables,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

MigrationState is persisted local migration metadata.

func LoadState

func LoadState(org, database, branch, migrationID string) (*MigrationState, error)

LoadState loads state using the default store.

func Status

func Status(org, database, branch, migrationID string) (*MigrationState, error)

Status returns migration state for status polling.

type NextStep

type NextStep struct {
	Tool    string `json:"tool,omitempty"`
	Command string `json:"command,omitempty"`
	Reason  string `json:"reason"`
}

NextStep guides agents to the next tool or command.

func DoctorNextSteps

func DoctorNextSteps(result *DoctorResult) []NextStep

DoctorNextSteps suggests next actions after doctor.

func LintNextSteps

func LintNextSteps(result *LintResult) []NextStep

LintNextSteps returns agent next steps based on lint results.

func StartNextSteps

func StartNextSteps(migrationID, database, branch, method, inputPath string, dryRun bool) []NextStep

StartNextSteps returns agent next steps after start or start --dry-run.

func StatusNextSteps

func StatusNextSteps(state *MigrationState) []NextStep

StatusNextSteps returns the recommended next command for the current migration phase.

func VerifyNextSteps

func VerifyNextSteps(migrationID, database, branch string) []NextStep

VerifyNextSteps returns next steps after a successful verify.

type NotifyAPIConfig

type NotifyAPIConfig struct {
	Client *ps.Client
	// Disabled skips notifications (internal use and tests).
	Disabled bool
}

NotifyAPIConfig carries the PlanetScale API client for async D1 import notifications.

type PgloaderOptions

type PgloaderOptions struct {
	SQLitePath string
	DestURI    string
	InputPath  string // dump path for column-level CAST rules
	WorkDir    string
	DryRun     bool
	DataOnly   bool
	// Tables loads one table per pgloader invocation when set (recommended for
	// large databases — avoids SBCL heap exhaustion from whole-catalog planning).
	Tables []string
	// SkipTables skips tables already loaded during a resumed import.
	SkipTables []string
	// OnTableLoaded is called after each table load succeeds (for resume checkpoints).
	OnTableLoaded func(table string) error
	// OnProgress reports per-table load progress.
	OnProgress ImportProgressFunc
	// PgloaderVerbose writes full pgloader output to stderr after each table.
	PgloaderVerbose bool
}

PgloaderOptions configures pgloader execution.

type PlanOptions

type PlanOptions struct {
	InputPath   string
	Org         string
	Database    string
	Branch      string
	Method      string
	MigrationID string      // optional: reuse an existing migration ID from plan/start
	Lint        *LintResult // optional: skip re-lint when already computed
}

PlanOptions configures migration planning.

type PlanResult

type PlanResult struct {
	MigrationID        string      `json:"migration_id"`
	InputPath          string      `json:"input_path"`
	Org                string      `json:"org"`
	Database           string      `json:"database"`
	Branch             string      `json:"branch"`
	RecommendedMethod  string      `json:"recommended_method"`
	EstimatedSizeBytes int64       `json:"estimated_size_bytes,omitempty"`
	Tables             []TablePlan `json:"tables"`
	CastRules          []CastRule  `json:"cast_rules"`
	LoadOrder          []string    `json:"load_order"`
	Issues             []Issue     `json:"issues"`
}

PlanResult is the migration plan JSON.

func Plan

func Plan(opts PlanOptions) (*PlanResult, error)

Plan builds a migration plan from a SQLite dump.

type Response

type Response struct {
	Status      string     `json:"status"`
	Command     string     `json:"command,omitempty"`
	Phase       string     `json:"phase,omitempty"`
	MigrationID string     `json:"migration_id,omitempty"`
	Issues      []Issue    `json:"issues,omitempty"`
	NextSteps   []NextStep `json:"next_steps,omitempty"`
	Reminder    string     `json:"reminder,omitempty"`
	Data        any        `json:"data,omitempty"`
	Error       *ErrorInfo `json:"error,omitempty"`
}

Response is the common JSON envelope for import d1 commands.

func BlockedStartResponse

func BlockedStartResponse(prepared *ImportPrepareResult, dryRun bool) Response

BlockedStartResponse builds the start error envelope when lint blocks import.

func CompleteResponse

func CompleteResponse(org, database, branch, migrationID string) (Response, error)

CompleteResponse builds the success envelope for import d1 complete.

func DoctorResponse

func DoctorResponse(result *DoctorResult) Response

DoctorResponse builds the doctor command envelope, including check details when not ready.

func ErrorResponse

func ErrorResponse(command string, err error) Response

ErrorResponse builds an error response from an error.

func LintResponse

func LintResponse(result *LintResult) Response

LintResponse builds the lint command envelope with status derived from issue severity.

func OKResponse

func OKResponse(command string, data any, next []NextStep) Response

OKResponse builds a success response.

func StatusResponse

func StatusResponse(state *MigrationState) Response

StatusResponse builds the status command envelope.

type SchemaParts

type SchemaParts struct {
	Tables  string
	Indexes string
}

SchemaParts holds table DDL and secondary index DDL separately so imports can load data before building indexes (much faster than maintaining indexes per row).

func ConvertSchemaParts

func ConvertSchemaParts(inputPath string) (SchemaParts, int, error)

ConvertSchemaParts converts SQLite DDL into Postgres table and index SQL.

type StateStore

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

StateStore manages local migration state.

func NewStateStore

func NewStateStore() (*StateStore, error)

NewStateStore returns the default state store location.

func (*StateStore) Delete

func (s *StateStore) Delete(org, database, branch, migrationID string) error

Delete removes migration state.

func (*StateStore) Load

func (s *StateStore) Load(org, database, branch, migrationID string) (*MigrationState, error)

Load retrieves migration state by ID.

func (*StateStore) Save

func (s *StateStore) Save(state *MigrationState) error

Save persists migration state.

type TableLoadTiming

type TableLoadTiming struct {
	Table string `json:"table"`
	Ms    int64  `json:"ms"`
}

TableLoadTiming is per-table pgloader duration.

type TablePlan

type TablePlan struct {
	Name        string `json:"name"`
	RowEstimate int    `json:"row_estimate,omitempty"`
	HasFK       bool   `json:"has_foreign_keys"`
}

TablePlan describes a table in the migration plan.

type TableSchema

type TableSchema struct {
	Name        string
	Columns     []ColumnSchema
	Constraints []string
	RawDDL      string
}

TableSchema holds parsed SQLite table metadata from a dump file.

func ParseDump

func ParseDump(path string) ([]TableSchema, error)

ParseDump reads a SQLite SQL dump and extracts table definitions.

type TableVerifyResult

type TableVerifyResult struct {
	Table      string `json:"table"`
	SourceRows int64  `json:"source_rows"`
	DestRows   int64  `json:"dest_rows"`
	Match      bool   `json:"match"`
}

TableVerifyResult is per-table verification.

type TypeCoercionContext

type TypeCoercionContext struct {
	Samples ColumnSamples
}

TypeCoercionContext carries sampled values used to validate name-based coercions.

func BuildTypeCoercionContext

func BuildTypeCoercionContext(inputPath string, tables []TableSchema) (*TypeCoercionContext, error)

type VerifyCheckResult

type VerifyCheckResult struct {
	Name    string `json:"name"`
	Table   string `json:"table,omitempty"`
	Column  string `json:"column,omitempty"`
	Matched bool   `json:"matched"`
	Message string `json:"message,omitempty"`
	Source  string `json:"source,omitempty"`
	Dest    string `json:"dest,omitempty"`
}

VerifyCheckResult is a single post-import verification check.

type VerifyOptions

type VerifyOptions struct {
	Org         string
	Database    string
	Branch      string
	MigrationID string
	InputPath   string
	SQLitePath  string
	DestURI     string
	DBName      string // destination PostgreSQL database name (default postgres)
	NotifyAPI   NotifyAPIConfig
	OnProgress  ImportProgressFunc
	// contains filtered or unexported fields
}

VerifyOptions configures post-import verification.

type VerifyResult

type VerifyResult struct {
	MigrationID string              `json:"migration_id"`
	Matched     bool                `json:"matched"`
	Tables      []TableVerifyResult `json:"tables"`
	Checks      []VerifyCheckResult `json:"checks,omitempty"`
}

VerifyResult compares source and destination after import.

func Verify

func Verify(ctx context.Context, opts VerifyOptions) (result *VerifyResult, err error)

Verify compares SQLite source data with PlanetScale Postgres after import.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL