@earth-app/collegedb 1.0.1

package/dist/kvmap.d.ts

@@ -0,0 +1,255 @@
+/**
+ * @fileoverview KV-based shard mapping implementation for CollegeDB
+ *
+ * This module provides the KVShardMapper class that uses Cloudflare KV storage
+ * to maintain mappings between primary keys and their assigned D1 database shards.
+ * It handles the persistence and retrieval of shard assignments, enabling the
+ * database router to consistently route queries to the correct shard.
+ *
+ * Key features:
+ * - Primary key to shard mapping storage and retrieval
+ * - Shard discovery and management
+ * - Key counting and statistics for load balancing
+ * - Batch operations for efficient KV usage
+ *
+ * @example
+ * ```typescript
+ * const mapper = new KVShardMapper(env.KV);
+ *
+ * // Set a mapping
+ * await mapper.setShardMapping('user-123', 'db-east');
+ *
+ * // Get a mapping
+ * const mapping = await mapper.getShardMapping('user-123');
+ * console.log(mapping?.shard); // 'db-east'
+ *
+ * // Get statistics
+ * const counts = await mapper.getShardKeyCounts();
+ * console.log(counts); // { 'db-east': 42, 'db-west': 38 }
+ * ```
+ *
+ * @author Gregory Mitchell
+ * @since 1.0.0
+ */
+import type { KVNamespace } from '@cloudflare/workers-types';
+import type { ShardMapping } from './types.js';
+/**
+ * The KVShardMapper class provides a persistent storage layer for mapping
+ * primary keys to their assigned D1 database shards. It uses Cloudflare KV
+ * for global, eventually consistent storage with low latency reads.
+ *
+ * Features:
+ * - CRUD operations for shard mappings
+ * - Atomic updates with timestamp tracking
+ * - Efficient bulk operations and statistics
+ * - Prefix-based key organization for performance
+ *
+ * @example
+ * ```typescript
+ * const mapper = new KVShardMapper(env.KV);
+ *
+ * // Create a new mapping
+ * await mapper.setShardMapping('order-456', 'db-central');
+ *
+ * // Update an existing mapping
+ * await mapper.updateShardMapping('order-456', 'db-west');
+ *
+ * // Query mapping
+ * const mapping = await mapper.getShardMapping('order-456');
+ * if (mapping) {
+ *   console.log(`Order 456 is on ${mapping.shard}`);
+ * }
+ * ```
+ */
+export declare class KVShardMapper {
+    private kv;
+    /**
+     * Cloudflare KV namespace for storing mappings
+     * @readonly
+     */
+    constructor(kv: KVNamespace);
+    /**
+     * Retrieves the shard assignment for a given primary key from KV storage.
+     * Returns null if no mapping exists, indicating the key has not been
+     * assigned to any shard yet.
+     * @param primaryKey - The primary key to look up
+     * @returns Promise resolving to the shard mapping or null if not found
+     * @throws {Error} If KV read operation fails
+     * @example
+     * ```typescript
+     * const mapping = await mapper.getShardMapping('user-789');
+     * if (mapping) {
+     *   console.log(`User 789 is on shard: ${mapping.shard}`);
+     *   console.log(`Created: ${new Date(mapping.createdAt)}`);
+     * } else {
+     *   console.log('User 789 not yet assigned to any shard');
+     * }
+     * ```
+     */
+    getShardMapping(primaryKey: string): Promise<ShardMapping | null>;
+    /**
+     * Creates a new shard assignment for a primary key. This is typically used
+     * when a new primary key is first encountered and needs to be assigned to
+     * a shard. Sets both created and updated timestamps to the current time.
+     *
+     * **Note**: This will overwrite any existing mapping for the same key.
+     * Use updateShardMapping() if you want to preserve creation timestamp.
+     * @param primaryKey - The primary key to map
+     * @param shard - The shard binding name to assign
+     * @returns Promise that resolves when the mapping is stored
+     * @throws {Error} If KV write operation fails
+     * @example
+     * ```typescript
+     * // Assign a new user to the west coast shard
+     * await mapper.setShardMapping('user-california-123', 'db-west');
+     * ```
+     */
+    setShardMapping(primaryKey: string, shard: string): Promise<void>;
+    /**
+     * Changes the shard assignment for a primary key that already has a mapping.
+     * Preserves the original creation timestamp while updating the modified
+     * timestamp. Throws an error if no existing mapping is found.
+     *
+     * This is typically used during shard rebalancing or data migration operations.
+     * @param primaryKey - The primary key to update
+     * @param newShard - The new shard binding name to assign
+     * @returns Promise that resolves when the mapping is updated
+     * @throws {Error} If no existing mapping found or KV operation fails
+     * @example
+     * ```typescript
+     * try {
+     *   // Move user to a different shard for rebalancing
+     *   await mapper.updateShardMapping('user-456', 'db-central');
+     *   console.log('User successfully moved to central shard');
+     * } catch (error) {
+     *   console.error('Failed to update mapping:', error.message);
+     * }
+     * ```
+     */
+    updateShardMapping(primaryKey: string, newShard: string): Promise<void>;
+    /**
+     * Completely removes the shard assignment for a primary key from KV storage.
+     * This is typically used when data is being permanently deleted or when
+     * cleaning up orphaned mappings.
+     *
+     * **WARNING**: After deletion, the primary key will be treated as new
+     * and may be assigned to a different shard on next access.
+     *
+     * @param primaryKey - The primary key mapping to remove
+     * @returns Promise that resolves when the mapping is deleted
+     * @throws {Error} If KV delete operation fails
+     * @example
+     * ```typescript
+     * // Remove mapping for deleted user
+     * await mapper.deleteShardMapping('user-deleted-789');
+     * console.log('Mapping removed for deleted user');
+     * ```
+     */
+    deleteShardMapping(primaryKey: string): Promise<void>;
+    /**
+     * Retrieves the list of all shard binding names that have been registered
+     * with the system. This is maintained separately from the individual mappings
+     * for efficient shard discovery.
+     *
+     * @returns Promise resolving to array of shard binding names
+     * @throws {Error} If KV read operation fails
+     * @example
+     * ```typescript
+     * const shards = await mapper.getKnownShards();
+     * console.log('Available shards:', shards);
+     * // Output: ['db-east', 'db-west', 'db-central']
+     * ```
+     */
+    getKnownShards(): Promise<string[]>;
+    /**
+     * Replaces the entire list of known shards with a new list. This is typically
+     * used during system initialization or when shards are added/removed in bulk.
+     *
+     * @param shards - Array of shard binding names to store
+     * @returns Promise that resolves when the list is updated
+     * @throws {Error} If KV write operation fails
+     * @example
+     * ```typescript
+     * // Update shard list after adding new regions
+     * await mapper.setKnownShards(['db-east', 'db-west', 'db-central', 'db-asia']);
+     * ```
+     */
+    setKnownShards(shards: string[]): Promise<void>;
+    /**
+     * Appends a new shard to the list of known shards if it's not already present.
+     * This operation is idempotent - adding the same shard multiple times has no effect.
+     *
+     * @param shard - The shard binding name to add
+     * @returns Promise that resolves when the shard is added
+     * @throws {Error} If KV operations fail
+     * @example
+     * ```typescript
+     * // Register a new shard when it comes online
+     * await mapper.addKnownShard('db-europe');
+     * console.log('European shard registered');
+     * ```
+     */
+    addKnownShard(shard: string): Promise<void>;
+    /**
+     * Scans all shard mappings to find primary keys assigned to the specified shard.
+     * This operation requires reading all mappings and can be expensive for large
+     * datasets. Consider caching results or using getShardKeyCounts() for statistics.
+     *
+     * @param shard - The shard binding name to search for
+     * @returns Promise resolving to array of primary keys assigned to the shard
+     * @throws {Error} If KV operations fail
+     * @example
+     * ```typescript
+     * // Find all users on the east coast shard
+     * const eastCoastUsers = await mapper.getKeysForShard('db-east');
+     * console.log(`East coast has ${eastCoastUsers.length} users`);
+     * ```
+     */
+    getKeysForShard(shard: string): Promise<string[]>;
+    /**
+     * Scans all shard mappings to count how many primary keys are assigned to
+     * each shard. Returns a mapping of shard names to their key counts. This
+     * is useful for load balancing and monitoring shard utilization.
+     *
+     * **Performance Note**: This operation scans all mappings and can be
+     * expensive for large datasets. Consider implementing caching for frequently
+     * accessed statistics.
+     *
+     * @returns Promise resolving to object mapping shard names to key counts
+     * @throws {Error} If KV operations fail
+     * @example
+     * ```typescript
+     * const counts = await mapper.getShardKeyCounts();
+     * console.log('Shard utilization:', counts);
+     * // Output: { 'db-east': 1247, 'db-west': 982, 'db-central': 1156 }
+     *
+     * // Find the least loaded shard
+     * const leastLoaded = Object.entries(counts)
+     *   .sort(([,a], [,b]) => a - b)[0][0];
+     * console.log('Least loaded shard:', leastLoaded);
+     * ```
+     */
+    getShardKeyCounts(): Promise<Record<string, number>>;
+    /**
+     * Deletes ALL shard mappings from KV storage. This is a destructive operation
+     * that removes all primary key assignments. After this operation, all keys
+     * will be treated as new and may be assigned to different shards.
+     *
+     * **DANGER**: This operation is irreversible and will cause data routing
+     * issues if used in production. Only use during development, testing, or
+     * complete system resets.
+     *
+     * @returns Promise that resolves when all mappings are deleted
+     * @throws {Error} If KV operations fail
+     * @example
+     * ```typescript
+     * // Only use in development/testing!
+     * if (process.env.NODE_ENV === 'development') {
+     *   await mapper.clearAllMappings();
+     *   console.log('All mappings cleared for testing');
+     * }
+     * ```
+     */
+    clearAllMappings(): Promise<void>;
+}
+//# sourceMappingURL=kvmap.d.ts.map

package/dist/kvmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kvmap.d.ts","sourceRoot":"","sources":["../src/kvmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyB/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,aAAa;IAKb,OAAO,CAAC,EAAE;IAJtB;;;OAGG;gBACiB,EAAE,EAAE,WAAW;IAEnC;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAMvE;;;;;;;;;;;;;;;;OAgBG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB7E;;;;;;;;;;;;;;;;;OAiBG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3D;;;;;;;;;;;;;OAaG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKzC;;;;;;;;;;;;OAYG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD;;;;;;;;;;;;;OAaG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjD;;;;;;;;;;;;;;OAcG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAcvD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAc1D;;;;;;;;;;;;;;;;;;;OAmBG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;CAKvC"}

package/dist/migrations.d.ts

@@ -0,0 +1,392 @@
+/**
+ * @fileoverview Database schema management and data migration utilities for CollegeDB
+ *
+ * This module provides utilities for managing database schemas across multiple D1 shards
+ * and migrating data between shards. It includes default schema definitions, schema
+ * validation, and data migration functions that ensure consistency across the distributed
+ * database system.
+ *
+ * Key features:
+ * - Default schema creation for typical use cases
+ * - Schema validation and existence checking
+ * - Data migration between D1 database instances
+ * - Batch schema operations across multiple shards
+ * - Table discovery and management utilities
+ *
+ * @example
+ * ```typescript
+ * import { createSchema, migrateRecord, schemaExists } from './migrations.js';
+ *
+ * // Create schema on a new shard
+ * await createSchema(env.DB_EAST);
+ *
+ * // Check if schema exists
+ * const hasSchema = await schemaExists(env.DB_WEST);
+ *
+ * // Migrate a user from one shard to another
+ * await migrateRecord(env.DB_EAST, env.DB_WEST, 'user-123', 'users');
+ * ```
+ *
+ * @author Gregory Mitchell
+ * @since 1.0.0
+ */
+import type { D1Database } from '@cloudflare/workers-types';
+import type { KVShardMapper } from './kvmap.js';
+import type { CollegeDBConfig, ShardingStrategy } from './types.js';
+/**
+ * Executes SQL statements to create the default table structure and indexes
+ * in the specified D1 database. Supports custom schemas and handles SQL
+ * statement parsing with comment filtering.
+ *
+ * The function:
+ * 1. Splits the schema into individual SQL statements
+ * 2. Filters out comments and empty statements
+ * 3. Executes each statement using prepared statements
+ * 4. Provides detailed error reporting on failures
+ *
+ * @param d1 - The D1 database instance to create schema in
+ * @param schema - Schema SQL to use
+ * @returns Promise that resolves when all schema statements are executed
+ * @throws {Error} If any schema statement fails with detailed error information
+ * @example
+ * ```typescript
+ * const sql = `
+ *   CREATE TABLE products (
+ *     id TEXT PRIMARY KEY,
+ *     name TEXT NOT NULL,
+ *     price REAL
+ *   );
+ * `;
+ * await createSchema(env.DB_PRODUCTS, sql);
+ * ```
+ */
+export declare function createSchema(d1: D1Database, schema: string): Promise<void>;
+/**
+ * Applies the schema to all provided D1 database instances in parallel.
+ * This is useful for initializing a complete sharded database system
+ * where all shards need the same table structure.
+ *
+ * The function executes schema creation on all shards concurrently for
+ * performance, but provides detailed error reporting that identifies
+ * which specific shard failed if any errors occur.
+ *
+ * @param shards - Record mapping shard names to D1 database instances
+ * @param schema - Schema SQL to use
+ * @returns Promise that resolves when schema is created on all shards
+ * @throws {Error} If schema creation fails on any shard, with shard identification
+ * @example
+ * ```typescript
+ * const shards = {
+ *   'db-east': env.DB_EAST,
+ *   'db-west': env.DB_WEST,
+ *   'db-central': env.DB_CENTRAL
+ * };
+ *
+ * try {
+ *   await createSchemaAcrossShards(shards);
+ *   console.log('Schema created on all shards successfully');
+ * } catch (error) {
+ *   console.error('Schema creation failed:', error.message);
+ *   // Error will specify which shard failed
+ * }
+ * ```
+ */
+export declare function createSchemaAcrossShards(shards: Record<string, D1Database>, schema: string): Promise<void>;
+/**
+ * Performs a lightweight check to determine if the expected schema is present
+ * in the database.
+ *
+ * @param d1 - The D1 database instance to check
+ * @param table - The name of the table to check
+ * @returns Promise resolving to true if schema tables exist, false otherwise
+ * @example
+ * ```typescript
+ * const hasSchema = await schemaExists(env.DB_NEW_SHARD, "users");
+ * if (!hasSchema) {
+ *     console.log('Creating schema on new shard...');
+ *     await createSchema(env.DB_NEW_SHARD, usersSchema);
+ * }
+ * ```
+ */
+export declare function schemaExists(d1: D1Database, table: string): Promise<boolean>;
+/**
+ * Removes all tables that are part of the default CollegeDB schema from
+ * the specified database. This is a destructive operation that cannot be undone.
+ *
+ * **DANGER**: This operation permanently deletes all data in the affected
+ * tables. Only use during development, testing, or complete system resets.
+ *
+ * @param d1 - The D1 database instance to drop tables from
+ * @param tables - The table schemas to drop
+ * @returns Promise that resolves when all tables are dropped
+ * @example
+ * ```typescript
+ * // Only use in development/testing environments!
+ * if (process.env.NODE_ENV === 'development') {
+ *   await dropSchema(env.DB_TEST);
+ *   console.log('Test database reset completed');
+ * }
+ * ```
+ */
+export declare function dropSchema(d1: D1Database, ...tables: string[]): Promise<void>;
+/**
+ * Queries the SQLite system catalog to retrieve all user-created tables
+ * in the database. This is useful for schema inspection, validation,
+ * and debugging purposes.
+ *
+ * @param d1 - The D1 database instance to inspect
+ * @returns Promise resolving to array of table names, sorted alphabetically
+ * @throws Returns empty array if query fails or database is inaccessible
+ * @example
+ * ```typescript
+ * const tables = await listTables(env.DB_EAST);
+ * console.log('Available tables:', tables);
+ * // Output: ['posts', 'shard_mappings', 'users']
+ *
+ * // Check for specific table
+ * if (tables.includes('users')) {
+ *   console.log('Users table exists');
+ * }
+ * ```
+ */
+export declare function listTables(d1: D1Database): Promise<string[]>;
+/**
+ * Moves a single record from a source D1 database to a target D1 database.
+ * This is typically used during shard rebalancing operations when data needs
+ * to be redistributed across shards for load balancing.
+ *
+ * The migration process:
+ * 1. Retrieves the complete record from the source database
+ * 2. Ensures the target database has the required schema
+ * 3. Inserts the record into the target database (using REPLACE for safety)
+ * 4. Deletes the record from the source database
+ *
+ * The operation is atomic from the perspective of each database, but not
+ * across databases. If the operation fails partway through, manual cleanup
+ * may be required.
+ *
+ * @param source - Source D1 database containing the record
+ * @param target - Target D1 database to receive the record
+ * @param primaryKey - Primary key of the record to migrate
+ * @param tableName - Name of the table containing the record
+ * @returns Promise that resolves when migration is complete
+ * @throws {Error} If source record not found, schema creation fails, or database operations fail
+ * @example
+ * ```typescript
+ * // Migrate a user from east to west shard
+ * try {
+ *   await migrateRecord(env.DB_EAST, env.DB_WEST, 'user-123', 'users');
+ *   console.log('User migration completed successfully');
+ * } catch (error) {
+ *   console.error('Migration failed:', error.message);
+ *   // May need manual cleanup depending on where it failed
+ * }
+ *
+ * // Migrate a post between shards
+ * await migrateRecord(source, target, 'post-456', 'posts');
+ * ```
+ */
+export declare function migrateRecord(source: D1Database, target: D1Database, primaryKey: string, tableName: string): Promise<void>;
+/**
+ * Scans an existing table to find all primary keys that need to be mapped to shards.
+ * This is useful when integrating CollegeDB with an existing database that already
+ * contains data. The function assumes the table has an 'id' column as the primary key.
+ *
+ * @param d1 - The D1 database instance to scan
+ * @param tableName - Name of the table to discover primary keys from
+ * @param primaryKeyColumn - Name of the primary key column (defaults to 'id')
+ * @returns Promise resolving to array of primary key values
+ * @throws {Error} If table doesn't exist or database query fails
+ * @example
+ * ```typescript
+ * // Discover all user IDs in an existing users table
+ * const userIds = await discoverExistingPrimaryKeys(env.DB_EXISTING, 'users');
+ * console.log(`Found ${userIds.length} existing users`);
+ *
+ * // Discover with custom primary key column
+ * const orderIds = await discoverExistingPrimaryKeys(env.DB_ORDERS, 'orders', 'order_id');
+ * ```
+ */
+export declare function discoverExistingPrimaryKeys(d1: D1Database, tableName: string, primaryKeyColumn?: string): Promise<string[]>;
+/**
+ * Takes a list of existing primary keys and creates shard mappings for them using
+ * the specified allocation strategy. This allows existing data to be integrated
+ * into the CollegeDB sharding system without data migration.
+ *
+ * @param primaryKeys - Array of primary key values to create mappings for
+ * @param shardBindings - Array of available shard binding names
+ * @param strategy - Allocation strategy to use ('hash', 'round-robin', or 'random')
+ * @param mapper - KVShardMapper instance for storing mappings
+ * @returns Promise that resolves when all mappings are created
+ * @throws {Error} If mapping creation fails
+ * @example
+ * ```typescript
+ * import { KVShardMapper } from './kvmap.js';
+ *
+ * const mapper = new KVShardMapper(env.KV);
+ * const existingIds = await discoverExistingPrimaryKeys(env.DB_EXISTING, 'users');
+ * const shards = ['db-east', 'db-west', 'db-central'];
+ *
+ * await createMappingsForExistingKeys(existingIds, shards, 'hash', mapper);
+ * console.log('All existing users mapped to shards');
+ * ```
+ */
+export declare function createMappingsForExistingKeys(primaryKeys: string[], shardBindings: string[], strategy: 'hash' | 'round-robin' | 'random', mapper: any): Promise<void>;
+/**
+ * Represents the result of validating a table for sharding.
+ * Contains information about the table structure, primary key, record count,
+ * and any issues encountered during validation.
+ */
+export type ValidationResult = {
+    isValid: boolean;
+    tableName: string;
+    primaryKeyColumn: string;
+    recordCount: number;
+    issues: string[];
+};
+/**
+ * Checks if a table exists and has a primary key column that can be used
+ * for sharding. Returns information about the table structure and primary key.
+ *
+ * @param d1 - The D1 database instance to check
+ * @param tableName - Name of the table to validate
+ * @param primaryKeyColumn - Expected primary key column name (defaults to 'id')
+ * @returns Promise resolving to validation result with table info
+ * @throws {Error} If table doesn't exist or validation fails
+ * @example
+ * ```typescript
+ * const validation = await validateTableForSharding(env.DB_EXISTING, 'users');
+ * if (validation.isValid) {
+ *   console.log(`Table ${validation.tableName} is ready for sharding`);
+ *   console.log(`Primary key: ${validation.primaryKeyColumn}`);
+ *   console.log(`Record count: ${validation.recordCount}`);
+ * } else {
+ *   console.error('Table validation failed:', validation.issues);
+ * }
+ * ```
+ */
+export declare function validateTableForSharding(d1: D1Database, tableName: string, primaryKeyColumn: string): Promise<ValidationResult>;
+/**
+ * Configuration options for integrating an existing database with CollegeDB.
+ * Allows customization of which tables to process, primary key column,
+ * sharding strategy, and whether to add the shard_mappings table.
+ */
+export type IntegrationOptions = {
+    tables?: string[];
+    primaryKeyColumn?: string;
+    strategy?: ShardingStrategy;
+    addShardMappingsTable?: boolean;
+    dryRun?: boolean;
+};
+/**
+ * Represents the result of integrating an existing database with CollegeDB.
+ * Contains information about the success of the integration, shard name,
+ * number of tables processed, total records integrated, mappings created,
+ * and any issues encountered during the process.
+ */
+export type IntegrationResult = {
+    success: boolean;
+    shardName: string;
+    tablesProcessed: number;
+    totalRecords: number;
+    mappingsCreated: number;
+    issues: string[];
+};
+/**
+ * Performs a complete drop-in integration of an existing database.
+ * This is the main function for integrating CollegeDB with an existing database
+ * that already contains data. It discovers tables, validates them, creates shard
+ * mappings, and optionally adds the shard_mappings table if needed.
+ *
+ * @param d1 - The existing D1 database to integrate
+ * @param shardName - The shard binding name for this database
+ * @param mapper - KVShardMapper instance for storing mappings
+ * @param options - Configuration options for the integration
+ * @returns Promise resolving to integration summary
+ * @throws {Error} If integration fails
+ * @example
+ * ```typescript
+ * import { KVShardMapper } from './kvmap.js';
+ *
+ * const mapper = new KVShardMapper(env.KV);
+ * const result = await integrateExistingDatabase(env.DB_EXISTING, 'db-existing', mapper, {
+ *   tables: ['users', 'posts'],
+ *   strategy: 'hash',
+ *   addShardMappingsTable: true
+ * });
+ *
+ * console.log(`Integrated ${result.totalRecords} records from ${result.tablesProcessed} tables`);
+ * ```
+ */
+export declare function integrateExistingDatabase(d1: D1Database, shardName: string, mapper: KVShardMapper, options?: IntegrationOptions): Promise<IntegrationResult>;
+/**
+ * Automatically detects if a database needs migration and performs it
+ *
+ * This function is called automatically by CollegeDB operations to detect
+ * existing databases that contain data but haven't been integrated into the
+ * sharding system. It performs seamless migration without user intervention.
+ *
+ * The detection process:
+ * 1. Checks if the database has data tables with primary keys
+ * 2. Verifies if primary key mappings exist in KV
+ * 3. If unmapped data is found, performs automatic integration
+ * 4. Caches results to avoid repeated checks
+ *
+ * @param d1 - The D1 database instance to check and potentially migrate
+ * @param shardName - The shard binding name for this database
+ * @param config - CollegeDB configuration containing KV and strategy
+ * @param options - Optional migration configuration
+ * @returns Promise resolving to migration result summary
+ * @example
+ * ```typescript
+ * // Called automatically by CollegeDB operations
+ * const result = await autoDetectAndMigrate(env.DB_EXISTING, 'db-existing', config);
+ * if (result.migrationPerformed) {
+ *   console.log(`Auto-migrated ${result.recordsMigrated} records`);
+ * }
+ * ```
+ */
+export declare function autoDetectAndMigrate(d1: D1Database, shardName: string, config: CollegeDBConfig, options?: {
+    primaryKeyColumn?: string;
+    tablesToCheck?: string[];
+    skipCache?: boolean;
+    maxRecordsToCheck?: number;
+}): Promise<{
+    migrationNeeded: boolean;
+    migrationPerformed: boolean;
+    recordsMigrated: number;
+    tablesProcessed: number;
+    issues: string[];
+}>;
+/**
+ * Performs a lightweight check to determine if a database contains
+ * existing data that hasn't been mapped to the sharding system.
+ * This is used internally to trigger automatic migration.
+ *
+ * @param d1 - The D1 database instance to check
+ * @param shardName - The shard binding name
+ * @param config - CollegeDB configuration
+ * @returns Promise resolving to true if migration is needed
+ * @example
+ * ```typescript
+ * const needsMigration = await checkMigrationNeeded(env.DB, 'db-main', config);
+ * if (needsMigration) {
+ *   console.log('Database contains unmapped data');
+ * }
+ * ```
+ */
+export declare function checkMigrationNeeded(d1: D1Database, shardName: string, config: CollegeDBConfig): Promise<boolean>;
+/**
+ * Clears the migration status cache
+ *
+ * Resets the internal cache used to track which databases have been
+ * checked for migration. Useful for testing or forcing re-checks.
+ *
+ * @example
+ * ```typescript
+ * // Force re-check of all databases
+ * clearMigrationCache();
+ * ```
+ */
+export declare function clearMigrationCache(): void;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"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"}