Class: SQLite::Database

Inherits:
Object
  • Object
show all
Defined in:
ext/sqlite.c

Constant Summary collapse

VERSION = 
rb_str_new2( sqlite_libversion() )
ENCODING = 
rb_str_new2( sqlite_libencoding() )

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(dbname, mode) ⇒ Object

Opens a SQLite database. If the database does not exist, it will be created. The mode parameter is currently unused and should be set to 0.



430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
 
# File 'ext/sqlite.c', line 430

static VALUE static_database_new( VALUE klass,
                                  VALUE dbname,
                                  VALUE mode )
{
  SQLITE_RUBY_DATA *hdb;
  sqlite *db;
  char   *s_dbname;
  int     i_mode;
  char   *errmsg;
  VALUE   v_db;

  Check_Type( dbname, T_STRING );
  Check_Type( mode,   T_FIXNUM );

  s_dbname = STR2CSTR(dbname);
  i_mode   = FIX2INT(mode);

  db = sqlite_open( s_dbname, i_mode, &errmsg );
  if( db == NULL )
  {
    VALUE err = rb_str_new2( errmsg );
    free( errmsg );

    static_raise_db_error( -1, "%s", STR2CSTR( err ) );
  }

  hdb = ALLOC( SQLITE_RUBY_DATA );
  hdb->db = db;
  hdb->use_array = 0; /* default to FALSE */

  v_db = Data_Wrap_Struct( klass, NULL, static_free_database_handle, hdb );

  static_set_type_translation( v_db, Qfalse );

  return v_db;
}

Instance Method Details

#changes ⇒ Object

Returns the number of rows that were affected by the last query.



574
575
576
577
578
579
580
581
582
583
584
 
# File 'ext/sqlite.c', line 574

static VALUE static_changes( VALUE self )
{
  SQLITE_RUBY_DATA *hdb;

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );

  if( hdb->db == NULL )
    static_raise_db_error( -1, "attempt to access a closed database" );

  return INT2FIX( sqlite_changes( hdb->db ) );
}

#close ⇒ Object

Closes an open database. No further methods should be invoked on the database after closing it.



472
473
474
475
476
477
478
479
480
481
482
483
484
 
# File 'ext/sqlite.c', line 472

static VALUE static_database_close( VALUE self )
{
  SQLITE_RUBY_DATA *hdb;

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );
  if( hdb->db != NULL )
  {
    sqlite_close( hdb->db );
    hdb->db = NULL;
  }

  return Qnil;
}

#complete?(sql) ⇒ Boolean

Queries whether or not the given SQL statement is complete or not. This is primarly useful in interactive environments where you are prompting the user for a query, line-by-line.

Returns:

  • (Boolean) 


611
612
613
614
615
616
617
 
# File 'ext/sqlite.c', line 611

static VALUE static_complete( VALUE self,
                              VALUE sql )
{
  Check_Type( sql, T_STRING );

  return ( sqlite_complete( STR2CSTR( sql ) ) ? Qtrue : Qfalse );
}

#create_aggregate(name, argc, step, finalize, parm) ⇒ Object

Defines a custom aggregate SQL function with the given name and argument count (argc). The step parameter must be a proc object, which will be called for each iteration during the processing of the aggregate. The finalize parameter must also be a proc object, and is called at the end of the processing of the aggreate. The parm parameter will be passed to both callbacks.



694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
 
# File 'ext/sqlite.c', line 694

static VALUE static_create_aggregate( VALUE self,
                                      VALUE name,
                                      VALUE argc,
                                      VALUE step,
                                      VALUE finalize,
                                      VALUE parm )
{
  SQLITE_RUBY_DATA *hdb;
  SQLITE_CUSTOM_FUNCTION_CB *data;
  char *s_name;
  int   i_argc;
  int   rc;

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );
  s_name = STR2CSTR( name );
  i_argc = FIX2INT( argc );

  if( hdb->db == NULL )
    static_raise_db_error( -1, "attempt to access a closed database" );

  data = ALLOC( SQLITE_CUSTOM_FUNCTION_CB );
  data->callback = step;
  data->finalize = finalize;
  data->arg = parm;

  rc = sqlite_create_aggregate( hdb->db,
                                s_name,
                                i_argc,
                                static_custom_aggregate_callback,
                                static_custom_finalize_callback,
                                data );

  if( rc != 0 )
    static_raise_db_error( rc, "error registering custom function" );

  return Qnil;
}

#create_function(name, argc, callback, parm) ⇒ Object

Defines a custom SQL function with the given name and expected parameter count. The callback must be a proc object, which will be invoked for each row of the result set. The parm will be passed to the callback as well.



651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
 
# File 'ext/sqlite.c', line 651

static VALUE static_create_function( VALUE self,
                                     VALUE name,
                                     VALUE argc,
                                     VALUE callback,
                                     VALUE parm )
{
  SQLITE_RUBY_DATA *hdb;
  SQLITE_CUSTOM_FUNCTION_CB *data;
  char *s_name;
  int   i_argc;
  int   rc;

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );
  s_name = STR2CSTR( name );
  i_argc = FIX2INT( argc );

  if( hdb->db == NULL )
    static_raise_db_error( -1, "attempt to access a closed database" );

  data = ALLOC( SQLITE_CUSTOM_FUNCTION_CB );
  data->callback = callback;
  data->arg = parm;

  rc = sqlite_create_function( hdb->db,
                               s_name,
                               i_argc,
                               static_custom_function_callback,
                               data );

  if( rc != 0 )
    static_raise_db_error( rc, "error registering custom function" );

  return Qnil;
}

#exec(sql, callback, parm) ⇒ Object

This is the base method used for querying the database. You will rarely use this method directly; rather, you should use the #execute method, instead. The sql parameter is the text of the sql to execute, callback is a proc object to be invoked for each row of the result set, and parm is an application-specific cookie value that will be passed to the callback.



494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
 
# File 'ext/sqlite.c', line 494

static VALUE static_database_exec( VALUE self,
                                   VALUE sql,
                                   VALUE callback,
                                   VALUE parm )
{
  SQLITE_RUBY_DATA *hdb;
  SQLITE_RUBY_CALLBACK hook;
  char *s_sql;
  int i;
  char *err = NULL;
  VALUE v_err;

  Check_Type( sql, T_STRING );
  s_sql = STR2CSTR(sql);

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );
  if( hdb->db == NULL )
    static_raise_db_error( -1, "attempt to access a closed database" );

  hook.callback = callback;
  hook.arg = parm;
  hook.built_columns = 0;
  hook.columns = Qnil;
  hook.self = hdb;
  hook.do_translate = ( rb_iv_get( self, "@type_translation" ) == Qtrue );

  if( static_pragma_enabled( hdb->db, "show_datatypes" ) )
  {
    hook.types = rb_hash_new();
  }
  else
  {
    hook.types = Qnil;
    hook.do_translate = 0; /* show_datatypes must be anbled for type translation */
  }

  i = sqlite_exec( hdb->db,
                   s_sql,
                   static_ruby_sqlite_callback,
                   &hook,
                   &err );

  if( err != 0 )
  {
    v_err = rb_str_new2( err );
    free( err );
  }

  switch( i )
  {
    case SQLITE_OK:
    case SQLITE_ABORT:
      break;
    default:
      static_raise_db_error( i, "%s", STR2CSTR(v_err) );
  }

  return INT2FIX(0);
}

#interrupt ⇒ Object

Interrupts the currently executing query, causing it to abort. If there is no current query, this does nothing.



591
592
593
594
595
596
597
598
599
600
601
602
603
 
# File 'ext/sqlite.c', line 591

static VALUE static_interrupt( VALUE self )
{
  SQLITE_RUBY_DATA *hdb;

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );

  if( hdb->db == NULL )
    static_raise_db_error( -1, "attempt to access a closed database" );

  sqlite_interrupt( hdb->db );

  return Qnil;
}

#last_insert_rowid ⇒ Object

Returns the key value of the last inserted row.



558
559
560
561
562
563
564
565
566
567
568
 
# File 'ext/sqlite.c', line 558

static VALUE static_last_insert_rowid( VALUE self )
{
  SQLITE_RUBY_DATA *hdb;

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );

  if( hdb->db == NULL )
    static_raise_db_error( -1, "attempt to access a closed database" );

  return INT2FIX( sqlite_last_insert_rowid( hdb->db ) );
}

#type_translation=(value) ⇒ Object

Specify whether or not the database should do automatic type translation.



772
773
774
775
776
777
778
779
780
781
782
783
784
 
# File 'ext/sqlite.c', line 772

static VALUE static_set_type_translation( VALUE self, VALUE value )
{
  if( value == Qnil || value == Qfalse )
  {
    value = Qfalse;
  }
  else
  {
    value = Qtrue;
  }

  return rb_iv_set( self, "@type_translation", value );
}

#type_translation? ⇒ Boolean

Query whether or not the database is doing automatic type translation between the SQLite type (always a string) and the corresponding Ruby type.

Returns:

  • (Boolean) 


764
765
766
767
 
# File 'ext/sqlite.c', line 764

static VALUE static_is_doing_type_translation( VALUE self )
{
  return rb_iv_get( self, "@type_translation" );
}

#use_array=(boolean) ⇒ Object

Causes the database instance to use an array to represent rows in query results, if ‘boolean’ is not Qnil or Qfalse.



623
624
625
626
627
628
629
630
631
632
 
# File 'ext/sqlite.c', line 623

static VALUE static_set_use_array( VALUE self, VALUE boolean )
{
  int use_array = RTEST( boolean );
  SQLITE_RUBY_DATA *hdb;

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );
  hdb->use_array = use_array;

  return boolean;
}

#use_array? ⇒ Boolean

Queries the database instance to determine whether or not arrays are being used to represent rows in query results.

Returns:

  • (Boolean) 


638
639
640
641
642
643
644
 
# File 'ext/sqlite.c', line 638

static VALUE static_is_use_array( VALUE self )
{
  SQLITE_RUBY_DATA *hdb;

  Data_Get_Struct( self, SQLITE_RUBY_DATA, hdb );
  return ( hdb->use_array ? Qtrue : Qfalse );
}