Class: DuckDB::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/duckdb/connection.rb,
ext/duckdb/connection.c

Overview

The DuckDB::Connection encapsulates connection with DuckDB database.

require 'duckdb'
db = DuckDB::Database.open
con = db.connect
con.query(sql)

Instance Method Summary collapse

Instance Method Details

#appender(table) {|appender| ... } ⇒ Object

returns Appender object. The first argument is table name

Yields:



130
131
132
133
134
135
136
137
138
 
# File 'lib/duckdb/connection.rb', line 130

def appender(table)
  appender = create_appender(table)

  return appender unless block_given?

  yield appender
  appender.flush
  appender.close
end

#async_query(sql, *args, **kwargs) ⇒ Object Also known as: async_execute

executes sql with args asynchronously. The first argument sql must be SQL string. The rest arguments are parameters of SQL string. This method returns DuckDB::PendingResult object.

require 'duckdb'
db = DuckDB::Database.open('duckdb_file')
con = db.connect

sql = 'SELECT * FROM users WHERE name = $name AND email = $email'
pending_result = con.async_query(sql, name: 'Dave', email: '[email protected]')
pending_result.execute_task while pending_result.state == :not_ready
result = pending_result.execute_pending
result.each.first



61
62
63
64
65
66
 
# File 'lib/duckdb/connection.rb', line 61

def async_query(sql, *args, **kwargs)
  prepare(sql) do |stmt|
    stmt.bind_args(*args, **kwargs)
    stmt.pending_prepared
  end
end

#async_query_stream(sql, *args, **kwargs) ⇒ Object

executes sql with args asynchronously and provides streaming result. The first argument sql must be SQL string. The rest arguments are parameters of SQL string. This method returns DuckDB::PendingResult object.

require 'duckdb'
db = DuckDB::Database.open('duckdb_file')
con = db.connect

sql = 'SELECT * FROM users WHERE name = $name AND email = $email'
pending_result = con.async_query_stream(sql, name: 'Dave', email: '[email protected]')

pending_result.execute_task while pending_result.state == :not_ready
result = pending_result.execute_pending
result.each.first



83
84
85
86
87
88
 
# File 'lib/duckdb/connection.rb', line 83

def async_query_stream(sql, *args, **kwargs)
  prepare(sql) do |stmt|
    stmt.bind_args(*args, **kwargs)
    stmt.pending_prepared_stream
  end
end

#connect(db) ⇒ Object Also known as: open

connects DuckDB database The first argument is DuckDB::Database object



92
93
94
95
96
97
98
99
100
101
 
# File 'lib/duckdb/connection.rb', line 92

def connect(db)
  conn = _connect(db)
  return conn unless block_given?

  begin
    yield conn
  ensure
    conn.disconnect
  end
end

#disconnect ⇒ Object Also known as: close 



59
60
61
62
63
64
65
66
 
# File 'ext/duckdb/connection.c', line 59

static VALUE duckdb_connection_disconnect(VALUE self) {
    rubyDuckDBConnection *ctx;

    TypedData_Get_Struct(self, rubyDuckDBConnection, &connection_data_type, ctx);
    duckdb_disconnect(&(ctx->con));

    return self;
}

#interrupt ⇒ nil

Interrupts the currently running query.

db = DuckDB::Database.open
conn = db.connect
con.query('SET ENABLE_PROGRESS_BAR=true')
con.query('SET ENABLE_PROGRESS_BAR_PRINT=false')
pending_result = con.async_query('slow query')

pending_result.execute_task
con.interrupt # => nil

Returns:

  • (nil) 


83
84
85
86
87
88
89
90
 
# File 'ext/duckdb/connection.c', line 83

static VALUE duckdb_connection_interrupt(VALUE self) {
    rubyDuckDBConnection *ctx;

    TypedData_Get_Struct(self, rubyDuckDBConnection, &connection_data_type, ctx);
    duckdb_interrupt(ctx->con);

    return Qnil;
}

#prepared_statement(str) ⇒ Object Also known as: prepare

returns PreparedStatement object. The first argument is SQL string. If block is given, the block is executed with PreparedStatement object and the object is cleaned up immediately.

require 'duckdb'
db = DuckDB::Database.open('duckdb_file')
con = db.connect

sql = 'SELECT * FROM users WHERE name = $name AND email = $email'
stmt = con.prepared_statement(sql)
stmt.bind_args(name: 'Dave', email: '[email protected]')
result = stmt.execute

# or
result = con.prepared_statement(sql) do |stmt|
           stmt.bind_args(name: 'Dave', email: '[email protected]')
           stmt.execute
         end



122
123
124
125
126
 
# File 'lib/duckdb/connection.rb', line 122

def prepared_statement(str, &)
  return PreparedStatement.new(self, str) unless block_given?

  PreparedStatement.prepare(self, str, &)
end

#query(sql, *args, **kwargs) ⇒ Object Also known as: execute

executes sql with args. The first argument sql must be SQL string. The rest arguments are parameters of SQL string.

require 'duckdb'
db = DuckDB::Database.open('duckdb_file')
con = db.connect
users = con.query('SELECT * FROM users')
sql = 'SELECT * FROM users WHERE name = ? AND email = ?'
dave = con.query(sql, 'Dave', '[email protected]')

# or You can use named parameter.

sql = 'SELECT * FROM users WHERE name = $name AND email = $email'
dave = con.query(sql, name: 'Dave', email: '[email protected]')



26
27
28
29
30
31
32
33
 
# File 'lib/duckdb/connection.rb', line 26

def query(sql, *args, **kwargs)
  return query_multi_sql(sql) if args.empty? && kwargs.empty?

  prepare(sql) do |stmt|
    stmt.bind_args(*args, **kwargs)
    stmt.execute
  end
end

#query_multi_sql(sql) ⇒ Object 



35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/duckdb/connection.rb', line 35

def query_multi_sql(sql)
  stmts = ExtractedStatements.new(self, sql)
  result = nil
  stmts.each do |stmt|
    result = stmt.execute
    stmt.destroy
  end
  result
ensure
  stmts&.destroy
end

#query_progress ⇒ Object

Returns the progress of the currently running query.

require 'duckdb'

db = DuckDB::Database.open
conn = db.connect
con.query('SET ENABLE_PROGRESS_BAR=true')
con.query('SET ENABLE_PROGRESS_BAR_PRINT=false')
con.query_progress # => -1.0
pending_result = con.async_query('slow query')
con.query_progress # => 0.0
pending_result.execute_task
con.query_progress # => Float



107
108
109
110
111
112
113
114
115
 
# File 'ext/duckdb/connection.c', line 107

static VALUE duckdb_connection_query_progress(VALUE self) {
    rubyDuckDBConnection *ctx;
    duckdb_query_progress_type progress;

    TypedData_Get_Struct(self, rubyDuckDBConnection, &connection_data_type, ctx);
    progress = duckdb_query_progress(ctx->con);

    return rb_funcall(mDuckDBConverter, rb_intern("_to_query_progress"), 3, DBL2NUM(progress.percentage), ULL2NUM(progress.rows_processed), ULL2NUM(progress.total_rows_to_process));
}