Move Tables from One Schema to Another

Description

Moves one or more tables from an existing schema to a new (target) schema using ⁠ALTER TABLE ... SET SCHEMA⁠. If the target schema does not exist, it is created first.

Usage

alter_table_schema(.con, from_table_names, new_schema)

Arguments

Details

• Ensures new_schema exists (⁠CREATE SCHEMA IF NOT EXISTS⁠).

• For each table in table_names, runs: ⁠ALTER TABLE old_schema.table SET SCHEMA new_schema⁠.

• Table and schema identifiers are safely quoted with glue::glue_sql().

Value

Invisibly returns a character vector of fully-qualified table names moved. Side effects: creates new_schema if needed and alters table schemas.

See Also

Other db-manage: copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Change Active Database and Schema

Description

Switches the active database and (optionally) schema for a valid DuckDB or MotherDuck connection. The function validates the target database and schema before executing the USE command and provides user feedback via CLI messages.

Usage

cd(.con, database_name, schema_name)

Arguments

Details

The cd() function is analogous to a "change directory" command in a file system, but for database contexts. It updates the currently active database (and optionally schema) for the given connection. If the target database or schema does not exist, the function aborts with a descriptive CLI error message.

Value

Invisibly returns a message summarizing the new connection context. Side effects include printing CLI headers showing the current user and database context.

See Also

Other db-meta: launch_ui(), pwd()

Examples

## Not run: 
# Connect to MotherDuck
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# List available databases
list_databases(con)

# Change to a specific database and schema
cd(con, database_name = "analytics_db", schema_name = "public")

# Disconnect
DBI::dbDisconnect(con)

## End(Not run)

Database, Schema, and Table Creator

Description

This function creates or inserts data into a specified database, schema, and table. If no database, schema, or table is provided, the function attempts to use the current database, schema, or table. It first checks if the provided database, schema, or table exists, and then either creates a new one or inserts into the existing one, based on the given parameters. It generates an action report indicating the status of the operation, whether a new database, schema, or table was created or whether existing ones were used.

Usage

cli_create_obj(.con, database_name, schema_name, table_name, write_type)

Arguments

Value

This function doesn't return any value. It generates a formatted report showing whether a new database, schema, or table was created or if existing ones were used.

CLI print deleted objects

Description

This function allows you to delete specified objects (database, schema, or table) from the connected database. The function will check if the provided database, schema, or table exists. If they do, it will proceed to delete them and print an action report detailing what was deleted and how many schemas or tables were affected. If the object does not exist, it will not delete anything.

Usage

cli_delete_obj(.con, database_name, schema_name, table_name)

Arguments

Value

This function does not return any values. It prints a message indicating the deleted objects (database, schema, or table) and the number of schemas/tables affected by the deletion.

Catalog Report Generator

Description

This function generates a report that provides details about the current database catalog, schema, and the number of resources (such as catalogs, tables, and shares) that the user has access to in the connected database. It also offers helpful functions for navigating the catalog, schema, and databases. The report includes:

• Current database (catalog)

• Current schema

• Number of catalogs the user has access to

• Number of tables the user has access to

• Number of shares the user has access to

that help manage and explore the database resources.

Usage

cli_show_db(.con)

Arguments

Value

This function doesn't return any value. It generates a formatted catalog report as output, including the current database, schema, and access counts for catalogs, tables, and shares.

User Information Report

Description

This function generates a report that shows the current user and their assigned role within the database. It queries the database to retrieve the current user using current_user() and the current role using current_role(). The output is displayed in a clear and formatted manner, with the user name and role listed in an unordered list.

Usage

cli_show_user(.con)

Arguments

Value

This function doesn't return any value. It generates a formatted user report with the current user's name and role as output.

DuckDB CSV read configuration (config_csv)

Description

A named character list of DuckDB CSV reading configuration settings used by the package. This includes options such as type detection, delimiter, quote handling, sample size, and other parser flags. These reflect the values returned by config_csv.

Usage

config_csv

Format

A named character list. Example names include:

all_varchar

character; "true"/"false"

allow_quoted_nulls

character; "true"/"false"

auto_detect

character; "true"/"false"

auto_type_candidates

character; types used for detection

buffer_size

character; buffer size in bytes

columns

character; column names/types struct or empty

delim

character; delimiter string

skip

character; number of lines to skip

Examples

## Not run: 
config_csv$all_varchar

## End(Not run)

DuckDB runtime database configuration (config_db)

Description

A named character list of DuckDB runtime configuration settings used by the package. This object includes allocator settings, thread counts, extension flags, storage and checkpoint options, security and secret settings, and other engine-level options. These settings reflect the values returned by config_db and are suitable as a template or reference for configuring DuckDB instances created via the package.

Usage

config_db

Format

A named character list. Example names and values include:

access_mode

character; e.g. "automatic"

allocator_background_threads

character; "true"/"false"

allocator_bulk_deallocation_flush_threshold

character; e.g. "512MB"

allocator_flush_threshold

character; e.g. "128MB"

allow_community_extensions

character; "true"/"false"

allow_extensions_metadata_mismatch

character; "true"/"false"

allow_persistent_secrets

character; "true"/"false"

allow_unredacted_secrets

character; "true"/"false"

allow_unsigned_extensions

character; "true"/"false"

arrow_large_buffer_size

character; "true"/"false"

arrow_lossless_conversion

character; "true"/"false"

arrow_output_list_view

character; "true"/"false"

autoinstall_extension_repository

character; URL or empty string

autoinstall_known_extensions

character; "true"/"false"

autoload_known_extensions

character; "true"/"false"

ca_cert_file

character; path to certificate file, or empty string

catalog_error_max_schemas

character; numeric as string, e.g. "100"

checkpoint_threshold

character; e.g. "16MB"

wal_autocheckpoint

character; e.g. "16MB"

custom_extension_repository

character; URL or empty string

custom_user_agent

character; string or empty

default_block_size

character; e.g. "262144"

default_collation

character; collation name or empty

default_null_order

character; e.g. "NULLS_LAST"

null_order

character; e.g. "NULLS_LAST"

default_order

character; e.g. "ASC"

default_secret_storage

character; e.g. "local_file"

disabled_compression_methods

character; list or empty

duckdb_api

character; e.g. "cli"

enable_external_access

character; "true"/"false"

enable_external_file_cache

character; "true"/"false"

enable_fsst_vectors

character; "true"/"false"

enable_http_metadata_cache

character; "true"/"false"

enable_macro_dependencies

character; "true"/"false"

enable_object_cache

character; "true"/"false"

enable_server_cert_verification

character; "true"/"false"

enable_view_dependencies

character; "true"/"false"

extension_directory

character; path or empty

external_threads

character; numeric as string, e.g. "1"

force_download

character; "true"/"false"

immediate_transaction_mode

character; "true"/"false"

index_scan_max_count

character; numeric as string, e.g. "2048"

index_scan_percentage

character; numeric as string, e.g. "0.001"

lock_configuration

character; "true"/"false"

max_vacuum_tasks

character; numeric as string, e.g. "100"

old_implicit_casting

character; "true"/"false"

parquet_metadata_cache

character; "true"/"false"

preserve_insertion_order

character; "true"/"false"

produce_arrow_string_view

character; "true"/"false"

scheduler_process_partial

character; "true"/"false"

secret_directory

character; path for persistent secrets

storage_compatibility_version

character; e.g. "v0.10.2"

temp_directory

character; path or empty string

threads

character; number of threads as string, e.g. "4"

worker_threads

character; number of threads as string, e.g. "4"

username

character; string or empty

user

character; string or empty

zstd_min_string_length

character; numeric as string, e.g. "4096"

Examples

# inspect the config
config_db
# access individual settings
config_db$threads

DuckDB Excel read configuration (config_excel)

Description

A named character list of DuckDB Excel reading configuration settings used by the package. Includes options such as reading binary as string, adding filename/row_number columns, Hive partitioning, and union by name. These reflect the values returned by config_excel.

Usage

config_excel

Format

A named character list. Example names include:

binary_as_string

character; "true"/"false"

encryption_config

character; encryption struct or "-" if none

filename

character; "true"/"false"

file_row_number

character; "true"/"false"

hive_partitioning

character; e.g., "(auto-detect)"

union_by_name

character; "true"/"false"

Examples

## Not run: 
config_excel$binary_as_string

## End(Not run)

DuckDB Parquet read configuration (config_parquet)

Description

A named character list of DuckDB Parquet reading configuration settings used by the package. Includes options such as binary encoding, filename columns, row numbers, and union by name. Reflects config_parquet.

Usage

config_parquet

Format

A named character list. Example names include:

binary_as_string

character; "true"/"false"

encryption_config

character; encryption struct or "-" if none

filename

character; "true"/"false"

file_row_number

character; "true"/"false"

hive_partitioning

character; e.g., "(auto-detect)"

union_by_name

character; "true"/"false"

Examples

## Not run: 
config_parquet$binary_as_string

## End(Not run)

Configure a MotherDuck user's settings

Description

Updates a MotherDuck user's configuration settings, including token type, instance size, and flock size. This function uses the MotherDuck REST API to apply the changes for the specified user.

Usage

configure_md_user_settings(
  user_name,
  motherduck_token = "MOTHERDUCK_TOKEN",
  token_type = "read_write",
  instance_size = "pulse",
  flock_size = 0
)

Arguments

Details

This function validates each parameter before making a PUT request to the MotherDuck API. It ensures that:

• token_type is valid using validate_token_type().

• instance_size is valid using validate_instance_size().

• flock_size is a valid integer using validate_flock_size(). The API response is returned as a tibble for easy inspection.

Value

A tibble containing the API response, including the updated settings for the user.

See Also

Other db-api: create_md_access_token(), create_md_user(), delete_md_access_token(), delete_md_user(), list_md_active_accounts(), list_md_user_instance(), list_md_user_tokens(), show_current_user()

Examples

## Not run: 
configure_md_user_settings(
  user_name = "alice",
  motherduck_token = "MOTHERDUCK_TOKEN",
  token_type = "read_write",
  instance_size = "pulse",
  flock_size = 10
)

## End(Not run)

Create connection to motherduck

Description

Establishes a connection to a MotherDuck account using DuckDB and the MotherDuck extension. The function handles token validation, database file creation, extension loading, and executes ⁠PRAGMA MD_CONNECT⁠ to authenticate the connection.

Usage

connect_to_motherduck(
  motherduck_token = "MOTHERDUCK_TOKEN",
  db_path = NULL,
  config
)

Arguments

Details

This function provides a convenient interface for connecting to MotherDuck. It allows you to:

• Use a token stored in an environment variable or supply the token directly.

• Optionally specify a persistent DuckDB database file or directory via db_path.

• Optionally Provide custom DuckDB configuration options via config.

• Automatically load the MotherDuck extension if not already loaded.

If db_path is not supplied, a temporary DuckDB database file will be created in the session's temporary directory. Use config to pass any DuckDB-specific options (e.g., memory limits or extensions).

Value

A DBIConnection object connected to your MotherDuck account.

Examples

## Not run: 
# Connect using a token stored in your .Renviron
con <- connect_to_motherduck()

# Connect with a direct token
con <- connect_to_motherduck(motherduck_token = "MY_DIRECT_TOKEN")

# Connect and specify a persistent database file
con <- connect_to_motherduck( )

## End(Not run)

Convert Table Metadata to SQL Identifiers

Description

Converts a tibble of table metadata (table_catalog, table_schema, table_name) into a list of DBI::Id SQL identifiers. Useful for safely quoting fully qualified table references in DBI/dbplyr workflows.

Usage

convert_table_to_sql_id(x)

Arguments

Value

A list of DBI::Id objects, each representing a fully-qualified table.

Copy Tables to a New Database/Schema

Description

Copies one or more tables to a new location (database/schema) by creating new tables via ⁠CREATE TABLE ... AS SELECT * FROM ...⁠. Requires motherduck connection

Usage

copy_tables_to_new_location(
  .con,
  from_table_names,
  to_database_name,
  to_schema_name
)

Arguments

Details

• Input from_table_names must contain columns: database_name, schema_name, and table_name.

• For each source table, the function issues: ⁠CREATE TABLE <to_db>.<to_schema>.<table> AS SELECT * FROM <src_db>.<src_schema>.<table>⁠.

• On local DuckDB (non-MotherDuck), the target database name is ignored and defaults to the current database of the connection.

Value

Invisibly returns a character vector of fully-qualified destination table names that were created. Side effect: creates target DB/schema if needed and writes new tables.

See Also

Other db-manage: alter_table_schema(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Create (If Not Exists) and Switch to a Database

Description

Ensures a database exists and sets it as the active database. If connected to MotherDuck, the function will run ⁠CREATE DATABASE IF NOT EXISTS⁠ followed by ⁠USE <database>⁠. Prints CLI status information about the current user and database.

Usage

create_database(.con, database_name)

Arguments

Details

• Connection type is checked via validate_md_connection_status() (with return_type = "arg").

• On MotherDuck, executes:

  • ⁠CREATE DATABASE IF NOT EXISTS <database>⁠

  • ⁠USE <database>⁠

• Displays status and environment info with CLI messages.

Value

Invisibly returns NULL. Side effect: may create a database and switches to it; prints CLI status

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Examples

## Not run: 
con_md <- connect_to_motherduck()
create_database(con_md, "analytics")

## End(Not run)

Create a MotherDuck database share if it does not exist

Description

Creates a new share for a specified database in MotherDuck if it does not already exist. Allows you to configure access, visibility, and update settings for the share.

Usage

create_if_not_exists_share(
  .con,
  share_name,
  database_name,
  access = "PUBLIC",
  visibility = "LISTED",
  update = "AUTOMATIC"
)

Arguments

Details

This function executes a ⁠CREATE IF NOT EXISTS⁠ SQL statement on the connected MotherDuck database to create a share for the specified database.

• access controls who can access the share.

• visibility controls whether the share is listed publicly or hidden.

• update controls whether changes to the source database are automatically reflected in the share. After creation, the current user is displayed for confirmation.

Value

A message confirming that the share has been created, if it did not already exist.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

create_if_not_exists_share(
  .con = con,
  share_name = "analytics_share",
  database_name = "sales_db",
  access = "PUBLIC",
  visibility = "LISTED",
  update = "AUTOMATIC"
)

## End(Not run)

Create a MotherDuck access token

Description

Creates a new access token for a specified MotherDuck user using the REST API. Tokens can be configured with a specific type, name, and expiration time.

Usage

create_md_access_token(
  user_name,
  token_type,
  token_name,
  token_expiration_number,
  token_expiration_unit,
  motherduck_token = "MOTHERDUCK_TOKEN"
)

Arguments

Details

This function calls the MotherDuck REST API endpoint ⁠https://api.motherduck.com/v1/users/{user_name}/tokens⁠ to create a new token for the specified user. The token’s time-to-live (TTL) is calculated in seconds from token_expiration_number and token_expiration_unit. The authenticated user must have administrative privileges to create tokens.

Value

A tibble containing the API response, including the username and the token attributes.

See Also

Other db-api: configure_md_user_settings(), create_md_user(), delete_md_access_token(), delete_md_user(), list_md_active_accounts(), list_md_user_instance(), list_md_user_tokens(), show_current_user()

Examples

## Not run: 
# Create a temporary read/write token for user "alejandro_hagan" valid for 1 hour
create_md_access_token(
  user_name = "alejandro_hagan",
  token_type = "read_write",
  token_name = "temp_token",
  token_expiration_number = 1,
  token_expiration_unit = "hours",
  motherduck_token = "MOTHERDUCK_TOKEN"
)

## End(Not run)

Create a new MotherDuck user

Description

Sends a POST request to the MotherDuck REST API to create a new user within your organization. This operation requires administrative privileges and a valid access token.

Usage

create_md_user(user_name, motherduck_token = "MOTHERDUCK_TOKEN")

Arguments

Details

This function calls the MotherDuck Users API endpoint to create a new user under the authenticated account. The provided token must belong to a user with permissions to manage organization-level accounts.

Value

A tibble summarizing the API response, typically containing the newly created username and associated metadata.

See Also

Other db-api: configure_md_user_settings(), create_md_access_token(), delete_md_access_token(), delete_md_user(), list_md_active_accounts(), list_md_user_instance(), list_md_user_tokens(), show_current_user()

Examples

## Not run: 
# Create a new user in MotherDuck using an admin token stored in an environment variable
create_md_user("test_20250913", "MOTHERDUCK_TOKEN")

## End(Not run)

Create or replace a MotherDuck database share

Description

Creates a new share or replaces an existing share for a specified database in MotherDuck. This allows you to update the configuration of an existing share or create a new one if it does not exist.

Usage

create_or_replace_share(
  .con,
  share_name,
  database_name,
  access = "PUBLIC",
  visibility = "LISTED",
  update = "AUTOMATIC"
)

Arguments

Details

This function executes a ⁠CREATE OR REPLACE SHARE⁠ SQL statement to create a new share or update an existing one.

• access controls who can access the share.

• visibility controls whether the share is listed publicly or hidden.

• update controls whether changes to the source database are automatically reflected in the share. The current user is displayed for confirmation before execution.

Value

A message indicating that the share has been created or replaced.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))
create_or_replace_share(
  .con = con,
  share_name = "analytics_share",
  database_name = "sales_db",
  access = "PUBLIC",
  visibility = "LISTED",
  update = "AUTOMATIC"
)

## End(Not run)

Create a Schema in a Database if It Does Not Exist

Description

Ensures that a specified schema exists in the given database. If the connection is to a MotherDuck instance, the function switches to the specified database before creating the schema. It also prints helpful connection and environment information via CLI messages for transparency.

Usage

create_schema(.con, database_name, schema_name)

Arguments

Details

• Uses DBI::dbExecute() with ⁠CREATE SCHEMA IF NOT EXISTS⁠ to create the schema only when needed.

• If connected to MotherDuck (determined by validate_md_connection_status()), executes ⁠USE <database>⁠ before creating the schema.

• Displays connection/user/database information via internal CLI helpers.

Value

Invisibly returns NULL. Side effect: creates the schema if necessary and prints CLI messages.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Create or Append a Table from a Tibble or DBI-Backed Table

Description

A thin wrapper that routes to either create_table_dbi() (for dbplyr-backed lazy tables, class "tbl_dbi") or create_table_tbl() (for in-memory tibbles / data frames), creating a physical table in the target database/schema. Supports overwrite and append write strategies and defers all heavy lifting to the specific implementation.

Usage

create_table(
  .data,
  .con,
  database_name,
  schema_name,
  table_name,
  write_type = "overwrite"
)

Arguments

Details

• If .data is a dbplyr lazy table (class "tbl_dbi"), the call is delegated to create_table_dbi().

• If .data is an in-memory tibble/data frame (class including "data.frame"), the call is delegated to create_table_tbl().

• Any other input classes trigger an error.

Value

Invisibly returns NULL. Side effect: writes a table to the database by delegating to the appropriate helper.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Create a Database Table from a DBI Object

Description

Creates a physical table in a database from a dbplyr/DBI-backed lazy table or query. The function supports both overwrite and append write strategies, automatically creates the target database and schema if they do not exist, and adds audit fields (upload_date, upload_time) to the written table.

Usage

create_table_dbi(
  .data,
  .con,
  database_name,
  schema_name,
  table_name,
  write_type = "overwrite"
)

Arguments

Details

• If the connection is a MotherDuck connection (detected by validate_md_connection_status()), the function ensures the database is created and switches to it before creating the schema.

• Adds two audit columns: upload_date (date of run) and upload_time (time and timezone of run).

• Uses DBI::Id() to explicitly target the database/schema/table.

• write_type = "overwrite" will drop and recreate the table.

• write_type = "append" will insert rows into an existing table.

Value

A user-friendly message is returned invisibly (invisible NULL), indicating whether the table was created or appended to. Side effect: writes data to the database.

Overwrite or Append a Local Tibble to a Database Table

Description

Takes an in-memory tibble (or data frame) and writes it to a database table using a DBI connection. The function supports both overwrite and append modes, automatically creates the target database and schema if they do not exist, and adds audit fields (upload_date, upload_time) to the written table.

Usage

create_table_tbl(
  .data,
  .con,
  database_name,
  schema_name,
  table_name,
  write_type = "overwrite"
)

Arguments

Details

• If the connection is a MotherDuck connection (detected by validate_md_connection_status()), the function ensures the database is created and switches to it before creating the schema.

• Two audit columns are added to the data before writing: upload_date (date of run) and upload_time (time and timezone of run).

• Uses DBI::Id() to explicitly target the database/schema/table.

• write_type = "overwrite" will drop and recreate the table.

• write_type = "append" will insert rows into an existing table.

Value

Invisibly returns NULL. Side effect: writes the tibble to the specified database table.

Drop and Recreate a Schema in a MotherDuck / DuckDB Database

Description

Drops an existing schema (if it exists) in the specified database and then creates a new empty schema. If the connection is to a MotherDuck instance, the function switches to the given database first, then drops and recreates the schema. Displays helpful CLI output about the current connection, user, and database.

Usage

delete_and_create_schema(.con, database_name, schema_name)

Arguments

Details

• Executes ⁠DROP SCHEMA IF EXISTS ... CASCADE⁠ to remove an existing schema and all contained objects.

• Executes ⁠CREATE SCHEMA IF NOT EXISTS⁠ to recreate it.

• If connected to MotherDuck (detected by validate_md_connection_status()), performs a ⁠USE <database>⁠ first.

• Prints a summary of the current connection and schema creation status using internal CLI helpers.

Value

Invisibly returns NULL. Side effect: drops and recreates the schema and prints CLI status messages.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Drop a Database

Description

Drops a database from the current DuckDB or MotherDuck connection if it exists. Prints a CLI status report after performing the operation.

Usage

delete_database(.con, database_name)

Arguments

Details

• Executes ⁠DROP DATABASE IF EXISTS <database_name>⁠ to remove the database.

• Intended for DuckDB or MotherDuck connections.

• Prints user, database and action details using CLI helper functions.

Value

Invisibly returns NULL. Side effect: drops the database and prints CLI status messages.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Delete a MotherDuck user's access token

Description

Deletes a specific access token for a given MotherDuck user using the REST API. This operation requires administrative privileges and a valid API token.

Usage

delete_md_access_token(
  user_name,
  token_name,
  motherduck_token = "MOTHERDUCK_TOKEN"
)

Arguments

Details

This function calls the MotherDuck REST API endpoint ⁠https://api.motherduck.com/v1/users/{user_name}/tokens/{token_name}⁠ using a DELETE request to remove the specified token. The authenticated user must have sufficient permissions to perform token management.

Value

A tibble summarizing the API response, typically including the username and deletion status of the token.

See Also

Other db-api: configure_md_user_settings(), create_md_access_token(), create_md_user(), delete_md_user(), list_md_active_accounts(), list_md_user_instance(), list_md_user_tokens(), show_current_user()

Examples

## Not run: 
# Delete a token named "temp_token" for user "alejandro_hagan"
delete_md_access_token(
  user_name = "alejandro_hagan",
  token_name = "temp_token",
  motherduck_token = "MOTHERDUCK_TOKEN"
)

## End(Not run)

Delete a MotherDuck user

Description

Sends a DELETE request to the MotherDuck REST API to permanently remove a user from your organization. This operation requires administrative privileges and a valid MotherDuck access token.

Usage

delete_md_user(user_name, motherduck_token = "MOTHERDUCK_TOKEN")

Arguments

Details

This function calls the MotherDuck Users API endpoint to delete the specified user. The authenticated user (associated with the provided token) must have sufficient permissions to perform user management actions.

Value

A tibble summarizing the API response, including the username and deletion status.

See Also

Other db-api: configure_md_user_settings(), create_md_access_token(), create_md_user(), delete_md_access_token(), list_md_active_accounts(), list_md_user_instance(), list_md_user_tokens(), show_current_user()

Examples

## Not run: 
# Delete a user named "bob_smith" using an admin token stored in an environment variable
delete_md_user("bob_smith", "MOTHERDUCK_TOKEN")

## End(Not run)

Drop a Schema from a Database

Description

Drops a schema from a specified database. Optionally cascades the deletion to all objects within the schema. Prints helpful CLI information about the current connection and action.

Usage

delete_schema(.con, database_name, schema_name, cascade = FALSE)

Arguments

Details

• Runs ⁠DROP SCHEMA IF EXISTS <db>.<schema>⁠ with optional CASCADE.

• Intended for DuckDB or MotherDuck connections.

• Uses CLI helpers to show current connection and report the deletion.

Value

Invisibly returns NULL. Side effect: drops the schema (and contained objects if cascade = TRUE) and prints CLI status.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Drop a Table

Description

Drops a table from the specified database and schema if it exists. Uses ⁠DROP TABLE IF EXISTS⁠ for safety and prints a CLI status report.

Usage

delete_table(.con, database_name, schema_name, table_name)

Arguments

Value

Invisibly returns NULL. Side effect: drops the table and prints CLI status messages.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Describe a MotherDuck share

Description

Retrieves detailed metadata about a specific share in MotherDuck, including the objects it contains, their types, and privileges granted.

Usage

describe_share(.con, share_name)

Arguments

Details

This function executes the md_describe_database_share system function to obtain comprehensive information about the specified share. The result is returned as a tibble for easy inspection and manipulation in R.

Value

A tibble containing metadata about the share, including object names, types, and privileges associated with the share.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), drop_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))
share_info <- describe_share(con, "analytics.sales_share")
print(share_info)

## End(Not run)

Drop a MotherDuck share

Description

Drops (deletes) a specified share from your MotherDuck account. If the share does not exist, a warning is displayed. This function safely validates the connection and share name before executing the operation.

Usage

drop_share(.con, share_name)

Arguments

Details

The function first validates that the connection is active. It then checks whether the specified share exists in the account. If it does, the share is dropped using a ⁠DROP SHARE IF EXISTS⁠ SQL command. If the share does not exist, a warning is shown. After the operation, the current user is displayed.

Value

Invisibly returns NULL. Side effect: the specified share is removed if it exists.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), list_owned_shares(), list_shared_with_me_shares(), upload_database_to_md()

Examples

## Not run: 
drop_share(con_md, "test_share")

## End(Not run)

Install DuckDB/MotherDuck Extensions

Description

Installs valid DuckDB or MotherDuck extensions for the current connection.

Usage

install_extensions(.con, extension_names)

Arguments

Details

The install_extensions() function validates the provided DuckDB/MotherDuck connection, then checks which of the requested extensions are valid. Valid extensions that are not already installed are installed using the INSTALL SQL command. Invalid extensions are reported to the user via CLI messages. This function provides a summary report describing which extensions were successfully installed and which were invalid.

Unlike load_extensions(), this function focuses purely on installation and does not automatically load extensions after installing.

Value

Invisibly returns NULL. A detailed CLI report of installation success/failure is printed.

See Also

Other db-con: load_extensions(), show_motherduck_token(), validate_extension_install_status(), validate_extension_load_status()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# Install the 'motherduck' extension
install_extensions(con, "motherduck")

# Install multiple extensions
install_extensions(con, c("fts", "httpfs"))

DBI::dbDisconnect(con)

## End(Not run)

Launch the DuckDB UI in your browser

Description

The launch_ui() function installs and launches the DuckDB UI extension for an active DuckDB database connection. This allows users to interact with the database via a web-based graphical interface.

The function will check that the connection is valid before proceeding.

Usage

launch_ui(.con)

Arguments

Details

The function performs the following steps:

• Checks that the provided DuckDB connection is valid. If the connection is invalid, it aborts with a descriptive error message.

• Installs the ui extension into the connected DuckDB instance.

• Calls the start_ui() procedure to launch the DuckDB UI in your browser.

This provides a convenient way to explore and manage DuckDB databases interactively without needing to leave the R environment.

Value

The function is called for its side effects and does not return a value. It launches the DuckDB UI and opens it in your default web browser.

See Also

Other db-meta: cd(), pwd()

Examples

## Not run: 
# Connect to DuckDB
con_db <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# Launch the DuckDB UI
launch_ui(con_db)

# Clean up
DBI::dbDisconnect(con_db, shutdown = TRUE)

## End(Not run)

List Databases Visible to the Connection

Description

Returns a lazy tibble of distinct database (catalog) names visible through the current connection, using information_schema.tables.

Usage

list_all_databases(.con)

Arguments

Details

The result is a dbplyr lazy table (tbl_dbi). Use dplyr::collect() to bring results into R as a local tibble.

Value

A dbplyr lazy tibble with one column: table_catalog.

See Also

Other db-list: list_all_tables(), list_current_schemas(), list_current_tables(), list_extensions(), list_fns(), list_setting(), list_shares()

List All Tables Visible to the Connection

Description

Returns a lazy tibble of all tables visible to the current connection by querying information_schema.tables (across all catalogs/databases and schemas).

Usage

list_all_tables(.con)

Arguments

Details

The result is a dbplyr lazy table (tbl_dbi). Use collect() to bring results into R as a local tibble.

Value

A dbplyr lazy tibble with columns:

• table_catalog — database/catalog name

• table_schema — schema name

• table_name — table name

See Also

Other db-list: list_all_databases(), list_current_schemas(), list_current_tables(), list_extensions(), list_fns(), list_setting(), list_shares()

List Schemas in the Current Database

Description

Returns a lazy tibble of all schemas in the current database of the connection. Queries information_schema.schemata and filters to the current database (catalog_name = current_database()).

Usage

list_current_schemas(.con)

Arguments

Details

• This function assumes the connection is valid (checked with validate_con()).

• Returns a dbplyr lazy table; use collect() to bring the result into R.

Value

A dbplyr lazy tibble with columns:

• catalog_name — the current database name.

• schema_name — each schema within that database.

See Also

Other db-list: list_all_databases(), list_all_tables(), list_current_tables(), list_extensions(), list_fns(), list_setting(), list_shares()

List Tables in the Current Database and Schema

Description

Returns a lazy tibble of all tables that exist in the current database and current schema of the active connection. Queries the standard information_schema.tables view and filters to current_database() and current_schema().

Usage

list_current_tables(.con)

Arguments

Details

• This function validates that the connection is valid with validate_con().

• Result is a dbplyr lazy table (tbl_dbi); call collect() to bring it into R.

Value

A dbplyr lazy tibble with columns:

• table_catalog — the current database.

• table_schema — the current schema.

• table_name — each table name.

See Also

Other db-list: list_all_databases(), list_all_tables(), list_current_schemas(), list_extensions(), list_fns(), list_setting(), list_shares()

List MotherDuck/DuckDB Extensions

Description

Retrieves all available DuckDB or MotherDuck extensions along with their descriptions, installation and load status.

Usage

list_extensions(.con)

Arguments

Details

The list_extensions() function queries the database for all extensions that are available in the current DuckDB or MotherDuck connection. The returned tibble includes information such as:

• extension_name: Name of the extension.

• description: Short description of the extension.

• installed: Logical indicating if the extension is installed.

• loaded: Logical indicating if the extension is currently loaded.

This is useful for determining which extensions can be installed or loaded using install_extensions() or load_extensions().

Value

A tibble with one row per extension and columns describing its metadata and current status.

See Also

Other db-list: list_all_databases(), list_all_tables(), list_current_schemas(), list_current_tables(), list_fns(), list_setting(), list_shares()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# List all available extensions
list_extensions(con)

DBI::dbDisconnect(con)

## End(Not run)

List Database Functions (DuckDB/MotherDuck)

Description

Returns a lazy table listing available SQL functions from the current DuckDB/MotherDuck connection using duckdb_functions().

Usage

list_fns(.con)

Arguments

Details

This wrapper validates the connection and then queries duckdb_functions() to enumerate function metadata. The result is a dbplyr lazy tibble (tbl_dbi); call collect() to materialize it in R.

Value

A dbplyr lazy tibble (tbl_dbi) with function metadata (e.g., function_name, schema, is_aggregate, is_alias, etc.).

See Also

Other db-list: list_all_databases(), list_all_tables(), list_current_schemas(), list_current_tables(), list_extensions(), list_setting(), list_shares()

List active MotherDuck accounts

Description

Retrieves a list of active MotherDuck accounts available to the authenticated user, returning the results as a tidy tibble.

Usage

list_md_active_accounts(motherduck_token = "MOTHERDUCK_TOKEN")

Arguments

Details

This function queries the MotherDuck REST API endpoint (⁠https://api.motherduck.com/v1/active_accounts⁠) using the provided or environment-resolved authentication token. The current user name is also displayed via show_current_user().

Value

A tibble with two columns:

• account_settings: configuration keys for the active accounts.

• account_values: corresponding configuration values.

See Also

Other db-api: configure_md_user_settings(), create_md_access_token(), create_md_user(), delete_md_access_token(), delete_md_user(), list_md_user_instance(), list_md_user_tokens(), show_current_user()

Examples

## Not run: 
# Retrieve active accounts for the authenticated user
accounts_tbl <- list_md_active_accounts()
print(accounts_tbl)

## End(Not run)

List a MotherDuck user's instance settings

Description

Retrieves configuration and instance-level settings for a specified MotherDuck user, returning the results as a tidy tibble.

Usage

list_md_user_instance(user_name, motherduck_token = "MOTHERDUCK_TOKEN")

Arguments

Details

This function calls the MotherDuck REST API endpoint ⁠https://api.motherduck.com/v1/users/{user_name}/instances⁠ to fetch information about the user’s active DuckDB instances and their configuration parameters.

The current authenticated user is displayed with show_current_user() for verification.

Value

A tibble with two columns:

• instance_desc: names or descriptions of instance configuration settings.

• instance_values: corresponding values for each configuration field.

See Also

Other db-api: configure_md_user_settings(), create_md_access_token(), create_md_user(), delete_md_access_token(), delete_md_user(), list_md_active_accounts(), list_md_user_tokens(), show_current_user()

Examples

## Not run: 
# List instance settings for a specific user
instance_tbl <- list_md_user_instance(user_name ="Bob Smith")

## End(Not run)

List a MotherDuck user's tokens

Description

Retrieves all active authentication tokens associated with a specific MotherDuck user account, returning them as a tidy tibble.

Usage

list_md_user_tokens(user_name, motherduck_token = "MOTHERDUCK_TOKEN")

Arguments

Details

This function queries the MotherDuck REST API endpoint ⁠https://api.motherduck.com/v1/users/{user_name}/tokens⁠ to list the tokens available for the specified user.

It uses the provided or environment-resolved motherduck_token for authorization. If motherduck_token is not explicitly provided, the function attempts to resolve it from the MOTHERDUCK_TOKEN environment variable The current authenticated user is displayed via show_current_user() for verification.

Value

A tibble with two columns:

• token_settings: metadata fields associated with each token.

• token_values: corresponding values for those fields.

See Also

Other db-api: configure_md_user_settings(), create_md_access_token(), create_md_user(), delete_md_access_token(), delete_md_user(), list_md_active_accounts(), list_md_user_instance(), show_current_user()

Examples

## Not run: 
# List tokens for a specific user
tokens_tbl <- list_md_user_tokens(user_name = "alejandro_hagan")
print(tokens_tbl)

## End(Not run)

List all shares owned by the current user

Description

Retrieves all database objects that are owned by the current authenticated user in MotherDuck.

Usage

list_owned_shares(.con)

Arguments

Details

This function executes the ⁠LIST SHARES;⁠ command to return metadata about all shares created by the current user. The returned tibble includes details such as the share name, type of object shared, and privileges granted.

Value

A tibble with one row per share owned by the current user, including columns for share name, object type, and granted privileges.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_shared_with_me_shares(), upload_database_to_md()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))
owned_tbl <- list_owned_shares(con)
print(owned_tbl)

## End(Not run)

List Database Settings

Description

The list_setting() function provides a convenient way to inspect the active configuration of a DuckDB or MotherDuck connection. It executes the internal DuckDB function duckdb_settings() and returns the results as a tidy tibble for easy viewing or filtering.

Usage

list_setting(.con)

Arguments

Details

This function is particularly useful for debugging or auditing runtime environments. All settings are returned as character columns, including their names, current values, and default values.

Value

A tibble::tibble containing one row per setting with columns describing the setting name, current value, description, and default value.

See Also

Other db-list: list_all_databases(), list_all_tables(), list_current_schemas(), list_current_tables(), list_extensions(), list_fns(), list_shares()

Examples

## Not run: 
# Connect to DuckDB
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# List all database settings
list_setting(con)

# Disconnect
DBI::dbDisconnect(con)

## End(Not run)

List all shares shared with the current user

Description

Retrieves all database objects that have been shared with the current authenticated user in MotherDuck.

Usage

list_shared_with_me_shares(.con)

Arguments

Details

This function queries the MD_INFORMATION_SCHEMA.SHARED_WITH_ME view to return metadata about all shares granted to the current user, including the owner, object name, type, and privileges. The result is returned as a tidy tibble for easy manipulation in R.

Value

A tibble containing one row per shared object, with columns describing the owner, object type, object name, and granted privileges.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), upload_database_to_md()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))
shared_tbl <- list_shared_with_me_shares(con)
print(shared_tbl)

## End(Not run)

List MotherDuck Shares

Description

The list_shares() function provides a convenient wrapper around the MotherDuck SQL command ⁠LIST SHARES;⁠. It validates that the supplied connection is an active MotherDuck connection before executing the query. If the connection is not valid, the function returns 0 instead of a table.

Usage

list_shares(.con)

Arguments

Details

MotherDuck supports object sharing, which allows users to list and access data shared between accounts. This function helps programmatically inspect available shares within an authenticated MotherDuck session.

Value

A tibble::tibble containing details of available shares if the connection is an MD connection or an empty tibble if not

See Also

Other db-list: list_all_databases(), list_all_tables(), list_current_schemas(), list_current_tables(), list_extensions(), list_fns(), list_setting()

Examples

## Not run: 
# Connect to MotherDuck
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# List shares
list_shares(con)

# Disconnect
DBI::dbDisconnect(con)

## End(Not run)

Load and Install DuckDB/MotherDuck Extensions

Description

Installs (if necessary) and loads valid DuckDB or MotherDuck extensions for the active connection.

Usage

load_extensions(.con, extension_names)

Arguments

Details

The load_extensions() function first validates the provided DuckDB/MotherDuck connection, then checks which of the requested extensions are valid and not already installed. Valid extensions are installed and loaded into the current session. Invalid extensions are reported to the user. The function provides a detailed CLI report summarizing which extensions were successfully installed and loaded, and which were invalid.

It is especially useful for ensuring that required extensions, such as motherduck, are available in your database session. The CLI messages also provide guidance on listing all available extensions and installing additional DuckDB extensions.

Value

Invisibly returns NULL. The function prints a CLI report of the extension status.

See Also

Other db-con: install_extensions(), show_motherduck_token(), validate_extension_install_status(), validate_extension_load_status()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# Install and load the 'motherduck' extension
load_extensions(con, "motherduck")

# Load multiple extensions
load_extensions(con, c("motherduck", "httpfs"))

DBI::dbDisconnect(con)

## End(Not run)

Print Current MotherDuck Database Context

Description

Displays the current database, schema, and role for the active DuckDB/MotherDuck connection. This mirrors the behavior of pwd in Linux by showing your current “working database.”

Usage

pwd(.con)

Arguments

Details

The pwd() function is a helper for inspecting the current database context of a DuckDB or MotherDuck connection. It queries the database for the current database, schema, and role. The database and schema are returned as a tibble for easy programmatic access, while the role is displayed using a CLI alert. This is especially useful in multi-database environments or when working with different user roles, providing a quick way to verify where SQL queries will be executed.

Value

A tibble with columns:

current_database

The active database name.

current_schema

The active schema name.

The current role is printed to the console via cli.

See Also

Other db-meta: cd(), launch_ui()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))
pwd(con)

## End(Not run)

Read a CSV file into a DuckDB/MotherDuck table

Description

Loads the DuckDB excel extension and creates a table from a CSV file using the read_csv_auto() table function. The destination is fully qualified as ⁠<database>.<schema>.<table>⁠. Only the options you supply are forwarded to read_csv_auto() (e.g., header, all_varchar, sample_size, names, types, skip, union_by_name, normalize_names, allow_quoted_nulls, ignore_errors). If names or types are not supplied, they are ignored. See the DuckDB read_csv_auto() documentation for more information.

Usage

read_csv(
  .con,
  to_database_name,
  to_schema_name,
  to_table_name,
  file_path,
  header,
  all_varchar,
  sample_size,
  names,
  types,
  skip,
  union_by_name,
  normalize_names,
  allow_quoted_nulls,
  ignore_errors,
  write_type,
  ...
)

Arguments

Value

Invisibly returns NULL. Side effect: creates ⁠<database>.<schema>.<table>⁠ with the CSV data

See Also

Other db-read: read_excel()

Read an Excel file into a DuckDB/MotherDuck table

Description

Loads the DuckDB excel extension and creates a table from an Excel file using the read_xlsx() table function. The destination is fully qualified as ⁠<database>.<schema>.<table>⁠. Only the options you supply are forwarded to read_xlsx() (e.g., sheet, header, all_varchar, ignore_errors, range, stop_at_empty, empty_as_varchar). See 'duckdb extension read_excel for more information

Usage

read_excel(
  .con,
  to_database_name,
  to_schema_name,
  to_table_name,
  file_path,
  header,
  sheet,
  all_varchar,
  ignore_errors,
  range,
  stop_at_empty,
  empty_as_varchar,
  write_type
)

Arguments

Value

Invisibly returns NULL. Side effect: creates ⁠<database>.<schema>.<table>⁠ with the Excel data.

See Also

Other db-read: read_csv()

Show current database user

Description

Return or print the current database user for a MotherDuck / DuckDB connection.

Usage

show_current_user(.con, motherduck_token, return = "msg")

Arguments

Details

This helper queries the active DB connection for the current user (via ⁠SELECT current_user⁠). You may either provide an existing DBI connection via .con or provide a motherduck_token and let the function open a short-lived connection for you. When the function opens a connection it will close it before returning.

The function supports two output modes:

• "msg" — prints a small informative message and returns the result invisibly (useful for interactive use),

• "arg" — returns a tibble containing the current_user column.

Value

a tibble

See Also

Other db-api: configure_md_user_settings(), create_md_access_token(), create_md_user(), delete_md_access_token(), delete_md_user(), list_md_active_accounts(), list_md_user_instance(), list_md_user_tokens()

Examples

## Not run: 
# Using an existing connection
con <- connect_to_motherduck("my_token")
show_current_user(.con = con, return = "msg")

# Let the function open a connection from a token
tbl <- show_current_user(motherduck_token = "my_token", return = "arg")

## End(Not run)

Show Your MotherDuck Token

Description

Displays the active MotherDuck authentication token associated with the current connection. Useful for debugging or verifying that your session is authenticated correctly.

Usage

show_motherduck_token(.con)

Arguments

Details

The show_motherduck_token() function executes the internal MotherDuck pragma print_md_token and returns the token information. This function should only be used in secure environments, as it exposes your authentication token in plain text. It requires a valid MotherDuck connection established with DBI::dbConnect().

Value

A tibble containing the current MotherDuck token.

See Also

Other db-con: install_extensions(), load_extensions(), validate_extension_install_status(), validate_extension_load_status()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))
show_motherduck_token(con)
DBI::dbDisconnect(con)

## End(Not run)

Summarize a Lazy DBI Table

Description

The summary.tbl_lazy() method provides a database-aware summary interface for lazy tables created via dbplyr. Instead of collecting data into R, it constructs a SQL SUMMARIZE query and executes it remotely, returning another lazy table reference.

Usage

## S3 method for class 'tbl_lazy'
summary(object, ...)

Arguments

Details

This method does not pull data into memory. Instead, it creates a new lazy query object representing the database-side summary. To retrieve the summarized data, use collect() on the returned object.

Value

A tbl_lazy object containing the summarized results, still backed by the remote database connection.

Examples

## Not run: 
library(DBI)
library(duckdb)
library(dplyr)

con <- dbConnect(duckdb::duckdb(dbdir = tempfile()))
dbWriteTable(con, "mtcars", mtcars)

tbl_obj <- tbl(con, "mtcars")

# Returns a lazy summary table
summary(tbl_obj)

dbDisconnect(con)

## End(Not run)

Upload a Local Database to MotherDuck

Description

Creates a new database on MotherDuck (if it does not exist) and copies all objects from an existing local database into it using the ⁠COPY FROM DATABASE⁠ command.

Usage

upload_database_to_md(.con, from_db_name, to_db_name)

Arguments

Details

• Runs ⁠CREATE DATABASE <to_db_name>⁠ if the target database does not exist.

• Then runs ⁠COPY FROM DATABASE <from_db_name> TO <to_db_name>⁠ to copy all objects (tables, views, etc.) from the local database.

• Prints a CLI status report (connection, user, current DB) after completion.

Value

Invisibly returns NULL. Side effect: creates the target database and copies all objects; prints a CLI action report.

See Also

Other db-manage: alter_table_schema(), copy_tables_to_new_location(), create_database(), create_if_not_exists_share(), create_or_replace_share(), create_schema(), create_table(), delete_and_create_schema(), delete_database(), delete_schema(), delete_table(), describe_share(), drop_share(), list_owned_shares(), list_shared_with_me_shares()

Examples

## Not run: 
con_db <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))
create_table(.con=con_db,.data=mtcars,database_name="memory",schema_name="main",table_name="mtcars")
con_md <- connect_to_motherduck()

upload_database_to_md(con_md, from_db_name = "memory", to_db_name = "analytics")

## End(Not run)

validate and Pprint your database location

Description

Internal function to help validate your local database location

Usage

validate_and_print_database_loction(.con)

Arguments

Value

print message

Validate connection is DuckDB

Description

Validates that your connection object is a DuckDB connection

Usage

validate_con(.con)

Arguments

Value

logical value or error message

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb())
validate_duckdb_con(con)

## End(Not run)

Validate Installed MotherDuck/DuckDB Extensions

Description

Checks whether specified DuckDB or MotherDuck extensions are installed and provides a detailed status report.

Usage

validate_extension_install_status(.con, extension_names, return_type = "msg")

Arguments

Details

The validate_extension_install_status() function validates the current connection and checks which of the requested extensions are installed. It produces a detailed CLI report showing which extensions are installed, not installed, or missing.

The function can return different outputs based on the return_type argument:

• "msg": prints a CLI report with extension statuses.

• "ext": returns a list containing success_ext (installed) and fail_ext (not installed).

• "arg": returns a logical value indicating whether all requested extensions are installed.

Value

Depending on return_type:

• "msg": prints CLI messages (invisible NULL).

• "ext": list with success_ext and fail_ext.

• "arg": logical indicating if all requested extensions are installed.

See Also

Other db-con: install_extensions(), load_extensions(), show_motherduck_token(), validate_extension_load_status()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# Print CLI report
validate_extension_install_status(con, extension_names = c("arrow", "excel"), return_type = "msg")

# Return a list of installed and failed extensions
validate_extension_install_status(con, extension_names = c("arrow", "excel"), return_type = "ext")

# Return logical indicating if all requested extensions are installed
validate_extension_install_status(con, extension_names = c("arrow", "excel"), return_type = "arg")

## End(Not run)

Validate Loaded MotherDuck/DuckDB Extensions

Description

Checks whether specified DuckDB or MotherDuck extensions are loaded in the current session and provides a detailed status report.

Usage

validate_extension_load_status(.con, extension_names, return_type = "msg")

Arguments

Details

The validate_extension_load_status() function validates the current connection, then checks which of the requested extensions are loaded. It produces a detailed CLI report showing which extensions are loaded, failed to load, or missing.

Depending on the return_type argument, the function can either print messages, return a list of extension statuses, or return a logical value indicating whether all requested extensions are successfully loaded.

Value

Depending on return_type:

• "msg": prints CLI messages (invisible NULL).

• "ext": list with success_ext, fail_ext, and missing_ext.

• "arg": logical indicating if all requested extensions are loaded.

See Also

Other db-con: install_extensions(), load_extensions(), show_motherduck_token(), validate_extension_install_status()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb(dbdir = tempfile()))

# Print CLI report
validate_extension_load_status(con, extension_names = c("excel", "arrow"), return_type = "msg")

# Return a list of loaded, failed, and missing extensions
validate_extension_load_status(con, extension_names = c("excel", "arrow"), return_type = "ext")

# Return logical indicating if all requested extensions are loaded
validate_extension_load_status(con, extension_names = c("excel", "arrow"), return_type = "arg")

## End(Not run)

Validate Mother Duck Connection Status

Description

Validates if you are successfully connected to motherduck database and will return either a logical value or print a message

Usage

validate_md_connection_status(.con, return_type = "msg")

Arguments

Value

logical value or warning message

See Also

connect_to_motherduck()

Examples

## Not run: 
con <- DBI::dbConnect(duckdb::duckdb())
validate_md_connection_status(con)

## End(Not run)