Class: Sequel::DuckDB::Database

Inherits:
Sequel::Database
  • Object
show all
Includes:
DatabaseMethods
Defined in:
lib/sequel/adapters/duckdb.rb

Overview

Database class for DuckDB adapter

This class extends Sequel::Database to provide DuckDB-specific functionality. It handles connection management, schema operations, and SQL execution for DuckDB databases. The class includes DatabaseMethods from the shared module to provide the core database functionality.

Examples:

Connecting to different database types

# In-memory database (data lost when connection closes)
db = Sequel::DuckDB::Database.new(database: ':memory:')

# File-based database (persistent storage)
db = Sequel::DuckDB::Database.new(database: '/path/to/database.duckdb')

# With configuration options
db = Sequel::DuckDB::Database.new(
  database: '/path/to/database.duckdb',
  config: { memory_limit: '4GB', threads: 8 }
)

Schema operations

# List all tables
db.tables  # => [:users, :products, :orders]

# Get table schema
db.schema(:users)  # => [[:id, {...}], [:name, {...}], ...]

# Check if table exists
db.table_exists?(:users)  # => true

See Also:

Since:

  • 0.1.0

Instance Method Summary collapse

Methods included from DatabaseMethods

#analyze_query, #auto_increment_column_sql, #auto_increment_sql, #begin_transaction, #commit_transaction, #configure_columnar_optimization, #configure_duckdb, #configure_memory_optimization, #configure_parallel_execution, #cpu_count, #database_error_classes, #database_exception_class, #database_exception_message, #database_exception_sqlstate, #database_exception_use_sqlstates?, #database_type, #execute, #execute_insert, #execute_statement, #execute_update, #explain_query, #folds_unquoted_identifiers_to_uppercase?, #get_config_value, #handle_constraint_violation, #in_transaction?, #indexes, #isolation_transaction, #log_connection_info?, #log_error, #log_info, #log_sql_error, #log_sql_query, #log_sql_timing, #log_warn, #map_duckdb_type_to_sequel, #parse_default_value, #parse_index_columns, #primary_key_column_sql, #query_plan, #quote_identifiers_default, #rollback_transaction, #savepoint_transaction, #schema, #schema_parse_indexes, #schema_parse_table, #schema_parse_tables, #set_config_value, #set_pragma, #supports_autocommit_control?, #supports_autocommit_disable?, #supports_autoincrement?, #supports_explain?, #supports_manual_transaction_control?, #supports_savepoints?, #supports_transaction_isolation_level?, #table_exists?, #tables, #transaction, #type_literal, #typecast_value, #typecast_value_time, #update_primary_key_info

Instance Method Details

#connect(server) ⇒ ::DuckDB::Connection

Connect to a DuckDB database

Creates a connection to either a file-based or in-memory DuckDB database. This method handles the low-level connection establishment and error handling.

Examples:

Connect to in-memory database

conn = connect(database: ':memory:')

Connect to file database

conn = connect(database: '/path/to/database.duckdb')

Connect with configuration

conn = connect(
  database: '/path/to/database.duckdb',
  config: { memory_limit: '2GB', threads: 4 }
)

Parameters:

  • server (Hash) —

    Server configuration options from Sequel

Options Hash (server):

  • :database (String) —

    Database path or ':memory:' for in-memory database

  • :config (Hash) —

    DuckDB-specific configuration options

  • :readonly (Boolean) —

    Whether to open database in read-only mode

Returns:

  • (::DuckDB::Connection) —

    Active DuckDB database connection

Raises:

  • (Sequel::DatabaseConnectionError) —

    If connection fails due to:

    • Invalid database path
    • Insufficient permissions
    • DuckDB library errors
    • Configuration errors

See Also:

Since:

  • 0.1.0



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/sequel/adapters/duckdb.rb', line 127

def connect(server) # rubocop:disable Metrics/MethodLength
  opts = server_opts(server)
  database_path = opts[:database]

  begin
    if database_path == ":memory:" || database_path.nil?
      # Create in-memory database and return connection
      db = ::DuckDB::Database.open(":memory:")
    else
      # Fix URI parsing issue - add leading slash if missing for absolute paths
      database_path = "/#{database_path}" if database_path.match?(/^[a-zA-Z]/) && !database_path.start_with?(":")

      # Create file-based database (will create file if it doesn't exist) and return connection
      db = ::DuckDB::Database.open(database_path)
    end
    db.connect
  rescue ::DuckDB::Error => e
    raise Sequel::DatabaseConnectionError, "Failed to connect to DuckDB database: #{e.message}"
  rescue StandardError => e
    raise Sequel::DatabaseConnectionError, "Unexpected error connecting to DuckDB: #{e.message}"
  end
end

#dataset_class_default ⇒ Class

Return the default dataset class for this database

This method is called by Sequel to determine which Dataset class to use when creating new datasets for this database connection.

Returns:

  • (Class) —

    The Dataset class to use for this database (always DuckDB::Dataset)

See Also:

Since:

  • 0.1.0



187
188
189
 
# File 'lib/sequel/adapters/duckdb.rb', line 187

def dataset_class_default
  Dataset
end

#disconnect_connection(conn) ⇒ void

This method returns an undefined value.

Disconnect from a DuckDB database connection

Parameters:

  • conn (::DuckDB::Connection) —

    The database connection to close

Since:

  • 0.1.0



154
155
156
157
158
159
160
161
162
 
# File 'lib/sequel/adapters/duckdb.rb', line 154

def disconnect_connection(conn)
  return unless conn

  begin
    conn.close
  rescue ::DuckDB::Error
    # Ignore errors during disconnect - connection may already be closed
  end
end

#valid_connection?(conn) ⇒ Boolean

Check if a DuckDB connection is valid and open

Parameters:

  • conn (::DuckDB::Connection) —

    The database connection to check

Returns:

  • (Boolean) —

    true if connection is valid and open, false otherwise

Since:

  • 0.1.0



168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/sequel/adapters/duckdb.rb', line 168

def valid_connection?(conn)
  return false unless conn

  begin
    # Try a simple query to check if the connection is still valid
    conn.query("SELECT 1")
    true
  rescue ::DuckDB::Error
    false
  end
end