@earth-app/collegedb
    Preparing search index...

    Function createClient

    • Creates a client: the router API bound to a configuration of its own.

      A client behaves as if it ran in a separate process. It shares no mapper, mapping cache, placement manifest or epoch, shard size cache, schema record, migration cache or phase observer with the module-level API, a scoped collegedb(config, callback) or any other client, even when they are given the same providers. Every method works the same as the function of the same name, and cached, invalidate and reconcileAllocations use the client's KV store, placement cache and coordinator.

      Nothing about a client needs AsyncLocalStorage: state travels with the object, so it is the isolation-safe choice on runtimes without an async context, and the one to use when several configurations serve requests in one isolate. The sync part of the configuration is applied before it returns, like initialize. Call initializeAsync on the client to wait for the background checks.

      Parameters

      Returns {
          createSchema: (db: SQLDatabase, schema: string) => Promise<void>;
          getClosestRegionFromIP: (request: Request) => D1Region;
          all<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<QueryResult<T>>;
          allAllShards<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<QueryResult<T>[]>;
          allAllShardsGlobal<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: GlobalAllShardsOptions<T>,
          ): Promise<QueryResult<T>>;
          allByLookupKey<T = Record<string, unknown>>(
              lookupKey: string,
              sql: string,
              bindings?: any[],
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<QueryResult<T>>;
          allShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<QueryResult<T>>;
          batch<T = Record<string, unknown>>(
              entries: BatchEntry[],
          ): Promise<BatchShardResult<T>[]>;
          cached<T>(
              key: string,
              fetcher: () => Promise<T>,
              options?: CacheOptions,
          ): Promise<T>;
          count(key: string, table: string, options?: ReadOptions): Promise<number>;
          countAllShards(
              table: string,
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<
              {
                  bookmarks?: Record<string, string>;
                  shards: ShardTableCount[];
                  total: number;
              },
          >;
          countShard(
              shardBinding: string,
              table: string,
              options?: ReadOptions,
          ): Promise<number>;
          deleteById<T = Record<string, unknown>>(
              key: string,
              table: string,
              id: string | number,
              options?: { idColumn?: string },
          ): Promise<QueryResult<T>>;
          deleteLookup(key: string, options?: LookupOptions): Promise<void>;
          deleteRow<T = Record<string, unknown>>(
              key: string,
              table: string,
              where: ColumnValues,
          ): Promise<QueryResult<T>>;
          ensureSchema(
              schema: string | string[],
              options?: EnsureSchemaOptions,
          ): Promise<void>;
          explain<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
              options?: Omit<ExplainOptions, "batchSize">,
          ): Promise<QueryResult<T>>;
          explainAllShards<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: ExplainOptions,
          ): Promise<QueryResult<T>[]>;
          explainShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
              options?: Omit<ExplainOptions, "batchSize">,
          ): Promise<QueryResult<T>>;
          first<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<T | null>;
          firstAllShards<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<(T | null)[]>;
          firstAllShardsGlobal<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: Omit<GlobalAllShardsOptions<T>, "limit">,
          ): Promise<T | null>;
          firstByLookupKey<T = Record<string, unknown>>(
              lookupKey: string,
              sql: string,
              bindings?: any[],
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<T | null>;
          firstResilient<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<T | null>;
          firstShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<T | null>;
          flush(): Promise<void>;
          getActiveConfig(): CollegeDBConfig | null;
          getDatabaseSizeForKey(key: string): Promise<number>;
          getDatabaseSizeForShard(shardBinding: string): Promise<number>;
          getDatabaseSizesAllShards(batchSize?: number): Promise<ShardSizeResult[]>;
          getLookup(key: string, options?: LookupOptions): Promise<string | null>;
          getMigrationStatus(
              key: string,
              table?: string,
          ): Promise<MigrationStatus | null>;
          getShardStats(): Promise<ShardStats[]>;
          getTotalDatabaseSize(batchSize?: number): Promise<number>;
          index<T = Record<string, unknown>>(
              key: string,
              table: string,
              columns: string | string[] | IndexColumnDefinition[],
              options?: Omit<CreateIndexOptions, "batchSize">,
          ): Promise<QueryResult<T>>;
          indexAllShards<T = Record<string, unknown>>(
              table: string,
              columns: string | string[] | IndexColumnDefinition[],
              options?: CreateIndexOptions,
          ): Promise<QueryResult<T>[]>;
          indexShard<T = Record<string, unknown>>(
              shardBinding: string,
              table: string,
              columns: string | string[] | IndexColumnDefinition[],
              options?: Omit<CreateIndexOptions, "batchSize">,
          ): Promise<QueryResult<T>>;
          initialize(config: CollegeDBConfig): void;
          initializeAsync(config: CollegeDBConfig): Promise<void>;
          initializeFromEnv(
              env: Record<string, unknown>,
              options?: InitializeFromEnvOptions,
          ): string[];
          insert<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: InsertOptions,
          ): Promise<InsertResult<T>>;
          insertInto<T = Record<string, unknown>>(
              key: string,
              table: string,
              values: ColumnValues,
              options?: BuildInsertOptions,
          ): Promise<QueryResult<T>>;
          insertReturning<T = Record<string, unknown>>(
              key: string,
              table: string,
              values: ColumnValues,
              options?: BuildInsertOptions & { idColumn?: string },
          ): Promise<T | null>;
          insertShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
              options?: InsertOptions,
          ): Promise<InsertResult<T>>;
          invalidate(
              prefix: string,
              options?: { concurrency?: number; kv?: KVStorage },
          ): Promise<number>;
          invalidateMappingCache(key?: string): Promise<void>;
          isInitialized(): boolean;
          listKnownShards(): Promise<string[]>;
          nextId(table: string, options?: NextIdOptions): Promise<number>;
          paginate<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: PaginateOptions<T>,
          ): Promise<PaginatedResult<T>>;
          patch<T = Record<string, unknown>>(
              key: string,
              table: string,
              id: string | number,
              values: ColumnValues,
              options?: IdColumnOptions,
          ): Promise<QueryResult<T>>;
          prepare(key: string, sql: string): Promise<PreparedStatement>;
          pruneEpochs(options: PruneOptions): Promise<PruneReport>;
          publishEligibility(): Promise<
              { eligible: string[]; epoch: number; published: boolean },
          >;
          purgeRetired(): Promise<PurgeReport>;
          query<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
          ): Promise<QueryResult<T>>;
          queryAll<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<QueryResult<T>>;
          queryFirst<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<T | null>;
          reassignShard(
              primaryKey: string,
              newBinding: string,
              tableName: string,
              options?: MoveRecordOptions,
          ): Promise<void>;
          rebalance(
              table: string,
              options?: { concurrency?: number; dryRun?: boolean },
          ): Promise<RebalanceResult>;
          reconcileAllocations(options?: ReconcileOptions): Promise<ReconcileReport>;
          recoverMigrations(
              options?: { olderThanMs?: number },
          ): Promise<RecoveryReport>;
          resetConfig(): void;
          run<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
          ): Promise<QueryResult<T>>;
          runAllShards<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              batchSize?: number,
          ): Promise<QueryResult<T>[]>;
          runShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
          ): Promise<QueryResult<T>>;
          setLookup(
              key: string,
              value: string,
              options?: LookupOptions,
          ): Promise<void>;
          updateRow<T = Record<string, unknown>>(
              key: string,
              table: string,
              values: ColumnValues,
              where: ColumnValues,
              options?: CrudReturningOptions,
          ): Promise<QueryResult<T>>;
          upsert<T = Record<string, unknown>>(
              key: string,
              table: string,
              values: ColumnValues,
              conflictColumns: string | string[],
              options?: BuildUpsertOptions,
          ): Promise<QueryResult<T>>;
          verifyMigrations(options?: { repair?: boolean }): Promise<VerifyReport>;
      }

      The client

      • createSchema: (db: SQLDatabase, schema: string) => Promise<void>

        Same as createSchema.

      • getClosestRegionFromIP: (request: Request) => D1Region

        Same as getClosestRegionFromIP.

      • all: function
        • all<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<QueryResult<T>>

          Same as all, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • key: string
          • sql: string
          • bindings: any[] = []
          • Optionaloptions: ReadOptions

          Returns Promise<QueryResult<T>>

      • allAllShards: function
        • allAllShards<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<QueryResult<T>[]>

          Same as allAllShards, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • sql: string
          • bindings: any[] = []
          • batchSize: number = 50
          • Optionaloptions: ReadOptions

          Returns Promise<QueryResult<T>[]>

      • allAllShardsGlobal: function
      • allByLookupKey: function
        • allByLookupKey<T = Record<string, unknown>>(
              lookupKey: string,
              sql: string,
              bindings?: any[],
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<QueryResult<T>>

          Same as allByLookupKey, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • lookupKey: string
          • sql: string
          • bindings: any[] = []
          • batchSize: number = 50
          • Optionaloptions: ReadOptions

          Returns Promise<QueryResult<T>>

      • allShard: function
        • allShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<QueryResult<T>>

          Same as allShard, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • shardBinding: string
          • sql: string
          • bindings: any[] = []
          • Optionaloptions: ReadOptions

          Returns Promise<QueryResult<T>>

      • batch: function
      • cached: function
        • cached<T>(
              key: string,
              fetcher: () => Promise<T>,
              options?: CacheOptions,
          ): Promise<T>

          Same as cached, reading and writing this client's KV store unless options.kv is set.

          Type Parameters

          • T

          Parameters

          • key: string
          • fetcher: () => Promise<T>
          • options: CacheOptions = {}

          Returns Promise<T>

      • count: function
        • count(key: string, table: string, options?: ReadOptions): Promise<number>

          Same as count, on this client.

          Parameters

          • key: string
          • table: string
          • Optionaloptions: ReadOptions

          Returns Promise<number>

      • countAllShards: function
        • countAllShards(
              table: string,
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<
              {
                  bookmarks?: Record<string, string>;
                  shards: ShardTableCount[];
                  total: number;
              },
          >

          Same as countAllShards, on this client.

          Parameters

          • table: string
          • batchSize: number = 50
          • Optionaloptions: ReadOptions

          Returns Promise<
              {
                  bookmarks?: Record<string, string>;
                  shards: ShardTableCount[];
                  total: number;
              },
          >

      • countShard: function
        • countShard(
              shardBinding: string,
              table: string,
              options?: ReadOptions,
          ): Promise<number>

          Same as countShard, on this client.

          Parameters

          • shardBinding: string
          • table: string
          • Optionaloptions: ReadOptions

          Returns Promise<number>

      • deleteById: function
        • deleteById<T = Record<string, unknown>>(
              key: string,
              table: string,
              id: string | number,
              options?: { idColumn?: string },
          ): Promise<QueryResult<T>>

          Same as deleteById, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • key: string
          • table: string
          • id: string | number
          • options: { idColumn?: string } = {}

          Returns Promise<QueryResult<T>>

      • deleteLookup: function
      • deleteRow: function
      • ensureSchema: function
      • explain: function
        • explain<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
              options?: Omit<ExplainOptions, "batchSize">,
          ): Promise<QueryResult<T>>

          Same as explain, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • key: string
          • sql: string
          • bindings: any[] = []
          • options: Omit<ExplainOptions, "batchSize"> = {}

          Returns Promise<QueryResult<T>>

      • explainAllShards: function
      • explainShard: function
        • explainShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
              options?: Omit<ExplainOptions, "batchSize">,
          ): Promise<QueryResult<T>>

          Same as explainShard, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • shardBinding: string
          • sql: string
          • bindings: any[] = []
          • options: Omit<ExplainOptions, "batchSize"> = {}

          Returns Promise<QueryResult<T>>

      • first: function
        • first<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<T | null>

          Same as first, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • key: string
          • sql: string
          • bindings: any[] = []
          • Optionaloptions: ReadOptions

          Returns Promise<T | null>

      • firstAllShards: function
        • firstAllShards<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<(T | null)[]>

          Same as firstAllShards, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • sql: string
          • bindings: any[] = []
          • batchSize: number = 50
          • Optionaloptions: ReadOptions

          Returns Promise<(T | null)[]>

      • firstAllShardsGlobal: function
        • firstAllShardsGlobal<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: Omit<GlobalAllShardsOptions<T>, "limit">,
          ): Promise<T | null>

          Same as firstAllShardsGlobal, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          Returns Promise<T | null>

      • firstByLookupKey: function
        • firstByLookupKey<T = Record<string, unknown>>(
              lookupKey: string,
              sql: string,
              bindings?: any[],
              batchSize?: number,
              options?: ReadOptions,
          ): Promise<T | null>

          Same as firstByLookupKey, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • lookupKey: string
          • sql: string
          • bindings: any[] = []
          • batchSize: number = 50
          • Optionaloptions: ReadOptions

          Returns Promise<T | null>

      • firstResilient: function
        • firstResilient<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<T | null>

          Same as firstResilient, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • key: string
          • sql: string
          • bindings: any[] = []
          • Optionaloptions: ReadOptions

          Returns Promise<T | null>

      • firstShard: function
        • firstShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<T | null>

          Same as firstShard, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • shardBinding: string
          • sql: string
          • bindings: any[] = []
          • Optionaloptions: ReadOptions

          Returns Promise<T | null>

      • flush: function
      • getActiveConfig: function
      • getDatabaseSizeForKey: function
      • getDatabaseSizeForShard: function
      • getDatabaseSizesAllShards: function
      • getLookup: function
      • getMigrationStatus: function
      • getShardStats: function
      • getTotalDatabaseSize: function
        • getTotalDatabaseSize(batchSize?: number): Promise<number>

          Same as getTotalDatabaseSize, on this client.

          Parameters

          • batchSize: number = 50

          Returns Promise<number>

      • index: function
      • indexAllShards: function
      • indexShard: function
      • initialize: function
      • initializeAsync: function
      • initializeFromEnv: function
      • insert: function
      • insertInto: function
      • insertReturning: function
      • insertShard: function
        • insertShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
              options?: InsertOptions,
          ): Promise<InsertResult<T>>

          Same as insertShard, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • shardBinding: string
          • sql: string
          • bindings: any[] = []
          • options: InsertOptions = {}

          Returns Promise<InsertResult<T>>

      • invalidate: function
        • invalidate(
              prefix: string,
              options?: { concurrency?: number; kv?: KVStorage },
          ): Promise<number>

          Same as invalidate, on this client's KV store unless options.kv is set.

          Parameters

          • prefix: string
          • options: { concurrency?: number; kv?: KVStorage } = {}

          Returns Promise<number>

      • invalidateMappingCache: function
      • isInitialized: function
      • listKnownShards: function
      • nextId: function
      • paginate: function
      • patch: function
      • prepare: function
      • pruneEpochs: function
      • publishEligibility: function
        • publishEligibility(): Promise<
              { eligible: string[]; epoch: number; published: boolean },
          >

          Same as publishEligibility, on this client.

          Returns Promise<{ eligible: string[]; epoch: number; published: boolean }>

      • purgeRetired: function
      • query: function
        • query<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
          ): Promise<QueryResult<T>>

          Same as query, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • sql: string
          • bindings: any[] = []

          Returns Promise<QueryResult<T>>

      • queryAll: function
        • queryAll<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<QueryResult<T>>

          Same as queryAll, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • sql: string
          • bindings: any[] = []
          • Optionaloptions: ReadOptions

          Returns Promise<QueryResult<T>>

      • queryFirst: function
        • queryFirst<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              options?: ReadOptions,
          ): Promise<T | null>

          Same as queryFirst, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • sql: string
          • bindings: any[] = []
          • Optionaloptions: ReadOptions

          Returns Promise<T | null>

      • reassignShard: function
        • reassignShard(
              primaryKey: string,
              newBinding: string,
              tableName: string,
              options?: MoveRecordOptions,
          ): Promise<void>

          Same as reassignShard, on this client.

          Parameters

          • primaryKey: string
          • newBinding: string
          • tableName: string
          • options: MoveRecordOptions = {}

          Returns Promise<void>

      • rebalance: function
        • rebalance(
              table: string,
              options?: { concurrency?: number; dryRun?: boolean },
          ): Promise<RebalanceResult>

          Same as rebalance, on this client.

          Parameters

          • table: string
          • options: { concurrency?: number; dryRun?: boolean } = {}

          Returns Promise<RebalanceResult>

      • reconcileAllocations: function
      • recoverMigrations: function
      • resetConfig: function
        • resetConfig(): void

          Same as resetConfig, on this client.

          Returns void

      • run: function
        • run<T = Record<string, unknown>>(
              key: string,
              sql: string,
              bindings?: any[],
          ): Promise<QueryResult<T>>

          Same as run, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • key: string
          • sql: string
          • bindings: any[] = []

          Returns Promise<QueryResult<T>>

      • runAllShards: function
        • runAllShards<T = Record<string, unknown>>(
              sql: string,
              bindings?: any[],
              batchSize?: number,
          ): Promise<QueryResult<T>[]>

          Same as runAllShards, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • sql: string
          • bindings: any[] = []
          • batchSize: number = 50

          Returns Promise<QueryResult<T>[]>

      • runShard: function
        • runShard<T = Record<string, unknown>>(
              shardBinding: string,
              sql: string,
              bindings?: any[],
          ): Promise<QueryResult<T>>

          Same as runShard, on this client.

          Type Parameters

          • T = Record<string, unknown>

          Parameters

          • shardBinding: string
          • sql: string
          • bindings: any[] = []

          Returns Promise<QueryResult<T>>

      • setLookup: function
      • updateRow: function
      • upsert: function
      • verifyMigrations: function

      INVALID_JOURNAL_SHARD when journalShard is not a configured shard

      1.4.0

      const tenantA = createClient({ kv: env.KV_A, shards: { 'db-a1': env.DB_A1, 'db-a2': env.DB_A2 } });
      const tenantB = createClient({ kv: env.KV_B, shards: { 'db-b1': env.DB_B1 } });

      await Promise.all([tenantA.run('user-1', 'INSERT INTO users (id) VALUES (?)', ['user-1']), tenantB.first('user-9', 'SELECT * FROM users WHERE id = ?', ['user-9'])]);

    Settings
    Member Visibility